Developing Webbloqs

This page is for developers working on the webbloqs library itself.

Testing Local Changes in Consumer Projects

When you make changes to webbloqs packages, you'll want to verify them in a real consumer project before publishing. The workflow uses pnpm tarballs and dependency overrides.

1. Build the package

pnpm dist

2. Create a tarball

cd packages/elements && pnpm pack
# Output: webbloqs-elements-4.1.0-RC.3.tgz

mv webbloqs-elements-4.1.0-RC.3.tgz ~/Downloads/

3. Configure the consumer project

Since @webbloqs/react depends on @webbloqs/elements, you typically need a transitive dependency override so that the override applies through the dependency chain. The version constraint on the parent (e.g., @webbloqs/react@^4.1.0-RC.3) ensures only the correct dependency chain is targeted.

pnpm v9 — in package.json:

{
    "overrides": {
        "@webbloqs/react@^4.1.0-RC.3>@webbloqs/elements@^4.1.0-RC.3": "file:/Users/ma/Downloads/webbloqs-elements-4.1.0-RC.3.tgz"
    }
}

pnpm v10+ — in pnpm-workspace.yaml:

overrides:
    "@webbloqs/react@^4.1.0-RC.3>@webbloqs/elements@^4.1.0-RC.3": "file:/Users/ma/Downloads/webbloqs-elements-4.1.0-RC.3.tgz"

Direct override (only when using elements without react):

{
    "overrides": {
        "@webbloqs/elements": "file:/Users/ma/Downloads/webbloqs-elements-4.1.0-RC.3.tgz"
    }
}

4. Reinstall

pnpm install

5. Clean up

Remove the overrides before committing changes to the consumer project.

Useful Commands

Command	Purpose
pnpm dist	Full production build (clean, lint, test, build, variations, SSR)
pnpm build	Build all packages (Nx cached)
pnpm test	Run all unit tests
pnpm lint	Lint scripts and styles
pnpm lint:fix	Auto-fix lint issues
pnpm serve	Storybook on port 8000
pnpm test:e2e:ci	Run E2E tests (starts server, runs Playwright)
pnpm run ci	Full CI pipeline (dist + e2e)

For all available scripts, see package.json in the repository root.