Skip to main content

Contributing to bestax-bulma

Thanks for your interest in contributing! This page mirrors the highlights of the repository's CONTRIBUTING.md — which stays the canonical source — and gives you a copy-pasteable local development command reference for the pnpm toolchain.

Requirements​

Before opening a PR, make sure:

  • All tests pass (pnpm test & pnpm test:coverage) — coverage must stay ≥ 95%.
  • Lint, format, and type checks pass (pnpm lint, pnpm format:check, pnpm typecheck).
  • Storybook covers UI changes — any UI change needs a corresponding story.
  • Docs are updated for new or changed behavior.
  • CI passes (pnpm all) and the PR targets main (direct pushes to main aren't allowed).

Prerequisites​

Use Node 22 (the LTS this repo targets — see .nvmrc). The repo uses pnpm, pinned via the packageManager field. The simplest way to get the exact version on any Node is to enable Corepack (bundled with Node):

corepack enable

pnpm powers the project's supply-chain hardening — lifecycle/postinstall scripts are blocked by default and a 3-day release-age cooldown prevents installing just-published versions. See pnpm-workspace.yaml for the exact settings.

Local Development Commands​

Everything here is safe to run locally; nothing publishes (see the note at the end).

1. One-time setup​

corepack enable                    # makes `pnpm` use the pinned pnpm@11.9.0
pnpm install --frozen-lockfile     # exact CI-parity install (fails if the lockfile drifts)
# or just `pnpm install` for a normal dev install

2. Run the whole CI suite locally (the big one)​

pnpm run all
# = turbo: build, typecheck, test, test:coverage, bundle:stats, lint,
#   format:check  &&  build-storybook (bulma-ui)

3. Individual checks​

pnpm run build          # turbo build all packages
pnpm run typecheck
pnpm run test           # jest (bulma-ui + create-bestax)
pnpm run test:coverage  # coverage (must stay >= 95%)
pnpm run lint
pnpm run format:check   # prettier check (use `pnpm run format` to auto-fix)
pnpm run bundle:stats   # writes bulma-ui/dist/stats.html

4. Docusaurus (docs site → http://localhost:3000)​

pnpm docs                                                   # dev server (hot reload)

# production build + preview:
pnpm exec turbo run build --filter=@allxsmith/bestax-docs   # builds docs + bulma-ui dep
pnpm --filter @allxsmith/bestax-docs run serve              # serves the built site

The build also regenerates /llms.txt and /llms-full.txt under docs/build/.

5. Storybook (→ http://localhost:6006)​

pnpm storybook                                              # dev server
pnpm --filter @allxsmith/bestax-bulma run build-storybook   # static build -> bulma-ui/storybook-static

6. Turbo directly (filters + caching)​

pnpm exec turbo run build --filter=@allxsmith/bestax-bulma   # one package (+ its deps)
pnpm exec turbo run test --filter=create-bestax
pnpm exec turbo run build                                    # everything (cached on re-run)
pnpm exec turbo run build --force                            # ignore turbo cache

7. create-bestax — scaffold a throwaway app​

Scaffold outside the repo so it's a standalone app (inside the repo you'd need --ignore-workspace):

pnpm --filter create-bestax run build
node "$PWD/create-bestax/dist/index.js" /tmp/my-bestax-app -t vite-ts -b complete -i fontawesome -y
cd /tmp/my-bestax-app && pnpm install && pnpm dev     # verify the generated app runs

8. Supply-chain / pnpm hardening checks​

pnpm audit --audit-level=high     # the CI gate (should exit 0)
pnpm approve-builds               # shows which install scripts are blocked/allowed
pnpm why serialize-javascript     # trace a transitive dep (confirms the >=7.0.3 override)
pnpm why prettier                 # confirm a single pinned version
pnpm outdated -r                  # what's behind (the cooldown may hold some back)
pnpm list --depth 0               # top-level deps per workspace
pnpm dedupe --check               # report duplicate versions without changing anything

Want to see the cooldown block something? Try adding a just-published package — pnpm refuses it (then discard the change):

pnpm add -w some-brand-new-package         # expect ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION
git checkout package.json pnpm-lock.yaml   # undo

9. Preview the release without publishing (semantic-release dry-run)​

Runs the real commit analysis and next-version calc, but publishes nothing:

export GITHUB_TOKEN=your_token   # the github plugin needs a repo-read token even in dry-run
cd bulma-ui      && pnpm exec semantic-release --dry-run --no-ci ; cd ..
cd create-bestax && pnpm exec semantic-release --dry-run --no-ci ; cd ..

It prints "The next release version is X.Y.Z" per package (or "no release") from your local commits — no npm publish, no tag, no GitHub release.

Safe to run; never publishes

Everything above is safe. The only things that actually publish are pnpm exec semantic-release without --dry-run (CI-only, on merge to main) and a manual pnpm publish --provenance --embed-readme --access public — neither of which is in this list. Those flags are not optional: pnpm defaults embed-readme to false and ignores publishConfig.provenance, which no package carries, so a bare pnpm publish ships unattested and loses the npm page's README. Every package publishes with pnpm publish, and each one's prepack and prepublishOnly hooks refuse the publishers they recognise as not being pnpm, so a stray npm publish or npm pack exits with an explanation rather than producing an unresolved workspace: specifier (#412). Both hooks are skipped by --ignore-scripts, and neither travels with a tarball that was packed elsewhere.

Workflow & conventions​

  1. Branch off main, make your change in the right workspace (bulma-ui, create-bestax, or docs).
  2. Add/update tests (≥ 95% coverage) and Storybook stories for UI changes.
  3. Run pnpm all, then open a PR targeting main.

Commits follow Conventional Commits — the type and scope drive semantic-release. Releasing types (feat, fix, perf, refactor, style) must be scoped to bulma-ui or create-bestax; docs, chore, ci, build, and test don't publish. Publishing uses npm OIDC trusted publishing with provenance (no long-lived token). See CONTRIBUTING.md for the full details.

AI-assisted development & review​

Every PR gets an automatic CodeRabbit review (address or refute its comments — it re-reviews on each push), and maintainers can invoke the @claude assistant (maintainer-only, since it spends the maintainer's Claude usage). Issues labeled claude-fix are implemented autonomously: Claude opens a PR labeled ai-loop that iterates with the AI reviewers until it converges, and a human always reviews and squash-merges the result. Don't touch the loop labels (ai-loop, needs-human-review, ai-loop-paused) on PRs you don't own. Full details: AI-Assisted Development.