Prerequisites
Before you begin, make sure you have the following installed:
| Tool | Version | Notes |
|---|
| Node.js | v18.x or higher | v22+ recommended |
| PNPM | v10 or higher | Required package manager |
| Volta | any | Optional, but recommended |
We recommend using Volta to manage your Node.js and PNPM versions. Once installed, Volta automatically switches to the correct versions pinned in package.json whenever you navigate to the BEEQ project directory — no manual version switching required. Setup steps
Fork and clone the repository
Fork the BEEQ repository on GitHub, then clone your fork locally:git clone https://github.com/<YOUR_GITHUB_USERNAME>/BEEQ.git BEEQ-Design-System
cd BEEQ-Design-System
git checkout main
Install dependencies
Install all workspace dependencies using PNPM’s frozen lockfile mode to ensure reproducible installs: Build the project
Run the initial build before starting the dev server. The build compiles StencilJS components and generates the framework output targets: Start the development server
Launch the development server and Storybook to begin working on components:Start coding! Monorepo structure
BEEQ is an NX monorepo with the following packages:
├── packages/
│ ├── beeq/ # Core web component library (@beeq/core)
│ ├── beeq-angular/ # Angular wrapper (@beeq/angular)
│ ├── beeq-react/ # React wrapper (@beeq/react)
│ ├── beeq-vue/ # Vue wrapper (@beeq/vue)
│ └── beeq-tailwindcss/ # TailwindCSS preset (@beeq/tailwindcss)
├── tools/
├── package.json
└── pnpm-lock.yaml
NX commands
Since the project uses NX, you can leverage powerful commands to work efficiently across the monorepo:
# Run tests only on projects affected by your changes
nx affected:test
# Build all packages
nx run-many --target=build --all
# Run lint on specific projects
nx run-many --target=lint --projects=beeq,beeq-react
These NX commands are also used in the CI pipeline to optimize build and test processes. See the CircleCI config for reference. Production build
To produce a production-ready build of all packages:
Branching strategy
BEEQ follows GitHub Flow. All branches are cut from main:
# New feature
git switch -c feat/<feature-name> main
# Bug fix
git switch -c fix/<fix-name> main
# Hotfix
git switch -c hotfix/<fix-name> main
# Tests or documentation
git switch -c tests/<test-change> main
git switch -c docs/<doc-change> main
Always branch off from main, not from an existing feature branch.
Recommended VS Code extensions
For the best development experience with Visual Studio Code, install these extensions:
Required
Nice to have
If you use a different editor, look for equivalent extensions that provide ESLint, Prettier, and Stylelint integration.