Getting Started

• Node.js 24 or newer (engines.node: >=24). The repo pins the version in .nvmrc (lts/*) and .tool-versions, so nvm use or mise install picks the right one.
• pnpm 11 - 11.22.0 is what CI runs. npm and yarn are not supported here; the workspace protocol (workspace:^0.0.1) that links the 57 component packages together is a pnpm feature.
• Chromium, installed for you by the postinstall hook (see below). Nothing else is needed - no Docker, no database, no environment variables.

There is no corepack step: pnpm is installed once, explicitly, and the same version is pinned in CI.

node --version                      # v24.x or newer
npm install --global pnpm@11.22.0   # or: brew install pnpm
pnpm --version                      # 11.22.0

pnpm install does three extra things beyond fetching dependencies:

1. links every packages/** workspace package so @root/core, @root/dom and each @root/<component> resolve locally;
2. runs playwright install chromium chromium-headless-shell (skipped when CI is set), because the unit, a11y and e2e suites all drive a real browser;
3. installs the Husky hooks - pre-commit runs lint and unit tests, pre-push runs the Playwright e2e and a11y suites.

If pnpm reports ignored build scripts, approve them once with pnpm approve-builds.

pnpm dev generates the site in development flavour and starts the Vite dev server: src/components.js imports @root/button and the rest from source (packages/components/Button/lib/index.js, through the aliases in vite.config.mjs), so a debugger in a constructor is hit and DevTools shows the file you are editing. Every component is on the site in this mode, including the ones still in progress - each marked WIP in the sidebar. Open http://localhost:1234.

pnpm start builds and serves dist/ with vite preview: the per-package build output, and only the components flagged root.readyForDev. That is what deploys, and what the e2e and a11y suites run against. Open http://localhost:1234.

Both pin port 1234, so run one at a time. The e2e and a11y suites take 4321 instead and build their own dist/, so pnpm test:e2e runs beside a live pnpm dev without adopting it - a suite pointed at the dev server measures transformed src/, not what deploys. root_DOCS_PORT moves the suites again if 4321 is taken.

A component is releasable when its own package.json says so:

{ "root": { "readyForDev": true } }

The component bundles are never re-bundled or minified by Vite. Each custom-element tag is derived from its class name, so a minifier that anonymises named classes would register every component as root- and nothing would upgrade. dist/ is exactly what gets deployed, which is why every Playwright suite runs against it.

Then reload the docs page. To rebuild a single package instead of all of them:

pnpm --filter @root/button run build

Documentation is part of the component: packages/components/<Name>/README.md is the docs page. After editing it, run pnpm docs:generate (or pnpm build) to regenerate src/index.html.

pnpm test:e2e runs 40 checks and starts its own server (pnpm build && vite preview), so allow it the first-run build time. An already running pnpm start is reused outside CI.

To run one component's unit tests:

pnpm --filter @root/button run test

The scaffolder copies scripts/templates/component, renames the placeholders, aligns the version and workspace dependencies, optionally adds the package to the root package.json and runs pnpm install. Use --dry-run first to see what it would touch. Afterwards, write the README against docs/component-readme-template.md - pnpm lint:readmes will hold you to it.

Remember the hooks: pre-commit runs pnpm lint and pnpm test, pre-push runs pnpm test:e2e.