BEEQ, a web component library initiative

This repository holds the source code of the web components present in the BEEQ Design System.

⚠️ Before Starting ⚠️

Structure 🧩

The project has been structured as an NX monorepo :

├── 📁 packages
  ├── 📁 beeq
  ├── 📁 beeq-angular
  ├── 📁 beeq-react
  ├── 📁 beeq-vue
  ├── ...
  ├── 📁 beeq-tailwindcss
  ├── ...
├── 📁 tools
├── package.json
├── package-lock.json

where:

• packages/beeq: Core library (source for all the elements/components implemented)
• packages/beeq-angular: Angular-specific wrapper for BEEQ core library
• packages/beeq-react: React.js-specific wrapper for BEEQ core library
• packages/beeq-vue: Vue.js-specific wrapper for BEEQ core library
• packages/beeq-tailwindcss: BEEQ's opinionated TailwindCSS configuration

Dependencies 📡

We recommend the use of Volta to manage Node and NPM versions. The installation process is pretty straightforward, and as referenced on their official site:

With Volta, you can select a Node engine once and then stop worrying about it. You can switch between projects and stop having to manually switch between Nodes.

Once you have Volta installed, whenever you change to the BEEQ folder locally, it will switch to the right Node and NPM versions pinned in the package.json:

  "volta": {
    "node": "20.11.1",
    "npm": "10.4.0"
  }

Volta is not mandatory, you can still use any Node/NPM setup that fits you most, just keep in mind that you'll need:

• NodeJS v18.x or higher
• NPM v8 or higher

Usage

The BEEQ components are published to the NPM package manager registry. You can use the @beeq/core or any of the framework-specific wrappers (@beeq/angular, @beeq/react) depending on the technology stack of your project. Make sure the follow the usage instructions for each package:

• 📘 How to use the @beeq/core package
• 📗 How to use the @beeq/angular package
• 📕 How to use the @beeq/react package
• 📙 How to use the @beeq/vue package
• 📓 How to use the @beeq/tailwindcss preset

Feel free to check our Storybook to see all the BEEQ components released. There you can find all the component's APIs (properties, events, and methods exposed) along with the variations that each component allows.

Running the project 🏃‍

To develop/extend components on the BEEQ Design System, please fork this repo in GitHub and clone it locally to a new directory:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/BEEQ.git BEEQ-Design-System
cd BEEQ-Design-System
git checkout main

Installation ⚙️

Simply run:

npm ci
# Make sure to build first the project before starting it
npm run build
npm start

Start coding 😃!

Build 📦

For a Production build, just run:

npm run build

Test 🧪

BEEQ uses Jest for unit tests and Jest and Puppeteer for end-to-end tests.

You can run all the tests once, by executing:

npm run test

🚨 If you get an error similar to the one below, try to check out locally the main branch and run the tests again.

fatal: Not a valid object name main
fatal: No such ref: 'main'
nx affected

Generate component

BEEQ comes with a component generator that saves you time when creating the skeleton for a new component. To use the generator, you just need to run the following command and follow the instructions in your prompt CLI:

npm run g

Contributing 💻

💥 If you are in the mood and want to help 🙂, please read carefully our Contributing Guidelines and Development Standards.

❗️ When working on a bug fix, new feature, etc., please notice that we follow a GitFlow workflow. Make sure to follow the instructions from the Contributing Branching Strategy guidelines about how to create your branch when starting to work on a bug/hot fixing, new feature, etc.

Documentation 📖

StencilJs

Need help? Check out the Stenciljs docs here (https://stenciljs.com/).

Tailwind CSS

We use Tailwind CSS for the style of the components, please take a look at their documentation here: (https://tailwindcss.com/docs/)

Thanks 🙏

We would like to express our sincere gratitude to Chromatic for providing the visual testing platform that enables us to review UI changes and identify visual regressions.

Thank you to the Nx team for helping us streamline our CI process and efficiently manage our Monorepo.