bestax / create-bestax
CLAUDE.md14 starsChanged 8 days agoMITView on GitHub
CLI that scaffolds a Vite app wired for @allxsmith/bestax-bulma. Agents and CI are first-class consumers: every prompt must have a flag equivalent, and the non-interactive path (-y + flags, no TTY) must never hang or regress (#192). So a question added later takes its default without a TTY, as --lint and --immediate do: a run that answered every older question by flag still finishes. --immediate never runs under -y or without a TTY unless it's passed, so a scripted run…
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bulma-ui/AGENTS.mdAGENTS.md
- bestax-mcp/CLAUDE.mdCLAUDE.md
- bestax-migrate/CLAUDE.mdCLAUDE.md
- bulma-ui/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- eslint-plugin/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- bulma-ui/llms.txtllms.txt
- bestax-custom-componentSkill
- bestax-formSkill
- bestax-iconsSkill
- bestax-layout-scaffoldSkill
- bestax-migrateSkill
- bestax-optimizeSkill
- bestax-themingSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Every flag is validated before anything on disk changes, and the directory is emptied only after the last prompt, so a typo or a Ctrl+C …
- Very specific: line 22
Every run goes through runCLI, which drops the -- that pnpm and bun forward verbatim, so <pm> create bestax my-app -- -t vite-ts works …
- Distinctive: line 115
When library conventions, skills, or the canonical docs entrypoint change (#203), check whether this template must change too.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
create-bestax — the npm create bestax scaffolder
CLI that scaffolds a Vite app wired for @allxsmith/bestax-bulma. Agents and CI are
first-class consumers: every prompt must have a flag equivalent, and the non-interactive
path (-y + flags, no TTY) must never hang or regress (#192). So a question added later takes
its default without a TTY, as --lint and --immediate do: a run that answered every older
question by flag still finishes. --immediate never runs under -y or without a TTY unless it's
passed, so a scripted run never starts a dev server it can't stop.
The one question -y does not answer is whether to delete a non-empty target directory: only
--overwrite or a yes at the prompt does, and without either the run stops and changes nothing.
Neither empties the working directory or a folder holding it (#310). The project directory can
be a path (#1154), so that is judged where the path resolves, not by how it is spelled. .
alone scaffolds into the working directory, as create-vite takes it, and so only while it's
empty. A directory holding only .git counts as empty, as create-vite counts it.
Every flag is validated before anything on disk changes, and the directory is emptied only after
the last prompt, so a typo or a Ctrl+C never costs the user their files (#945).
Architecture
src/index.ts— bin entry (Node version check);src/cli.ts— the commander program. Every run goes throughrunCLI, which drops the--that pnpm and bun forward verbatim, so<pm> create bestax my-app -- -t vite-tsworks under every package manager (#950)src/prompts.ts— interactive questions (each maps to a flag)src/project-creator.ts— writes the project: copies a template, injects options, installs skills, writesCLAUDE.mdsrc/constants.ts— user-facing strings and scaffolded-file templates (e.g. theCLAUDE_MDtemplate written into generated apps)src/library-range.ts— the@allxsmith/bestax-bulmarange a scaffold gets (see Dependencies)src/validators.ts,src/display.ts,src/file-system.ts— support modulessrc/run-command.ts— runs--immediate's install and dev servertemplates/vite,templates/vite-ts— the app templates. Thevite-compilerandvite-compiler-tstemplates copy them and turn the React Compiler on (setupReactCompiler). The Next.js templates (templates/next,templates/next-ts) are Next.js App Router skeletons with no starter page of their own:copyTemplatecopiessrc/App,src/App.cssandsrc/index.cssin fromviteorvite-ts(Template.starter) and appliesNEXT_STARTER_EDITS('use client', Next.js for Vite, no Vite logo). Each edit must match, so a change to the Vite starter page that breaks one fails the scaffold, andtemplates.test.ts, rather than shipping a half-adapted page.entryFilenames where a template loads its stylesheets and wraps the app:src/mainfor Vite,src/app/layoutfor Next.js, where the flavor, icon and provider steps write, the provider around everything in<body>. A Next.js app's title is its layout'smetadata.title, Ionicons load throughnext/script, and itslaunch.json(NEXT_LAUNCH_JSON) runsnext dev --port 3000, which fails rather than moving when the port is busy.--lint eslintwrites create-next-app'seslint-config-nextsetup (NEXT_ESLINT_*). The About page stays a Server Component, which needs bestax-bulma's'use client'modules (#1355): a scaffold floored below the release that added them failsnext build. The router templates (react-router,react-router-tsandtanstack-router-ts) copy them and lay the files intemplates/overlays/<router>/<vite|vite-ts>over them (setupRouter): a navbar layout, the routes and a second page, withApp, the starter page, as the home page. That step runs after the flavor, icon and provider steps, which editAppand the entry file as they do in the plain template, and then makes the entry file render the router where it renderedApp. The files it adds use no helper prop, so a no-helpers flavor needs nothing from it, andsrc/__tests__/templates.test.tsholds them to that.ROUTER_SETUPSinsrc/constants.tsholds what each router adds: its dependency, floored at a release past the cooldown, any Node floor it needs, and its README andCLAUDE.mdtext. Move a router's floor with its major, and check its Node floor when you do. The TanStack Router navbar links throughcreateLink(NavbarLink) rather thanas={Link}, sinceaskeeps the props but stops checkingtoagainst the routes.
Dependencies
@allxsmith/bestax-bulma is a declared runtime dependency (#644). The scaffolder is built for
the library and its manifest says so, the way bulma-ui declares bulma without importing it:
nothing in src/ imports the library, and the e2e installs from the registry with
--ignore-workspace. It is spelled workspace:^, which pnpm publish rewrites to the release
current at pack time (bulma-ui releases first in the same job), and the sibling rule in
check:conformance allows it only because SIBLING_RUNTIME_DEPS declares this exact pair.
What a consumer sees: npm create bestax installs the library, bulma, and react/react-dom
alongside the CLI.
A scaffolded app depends on the library at that same range (#1240). src/library-range.ts
reads it from this manifest at run time, so a published CLI floors the app at the release it
was packed with, and a CLI run from a checkout resolves workspace:^ from the library the
workspace links, the way pnpm publish would. The templates spell it workspace:^ too, a
placeholder the scaffold always replaces: one that slipped through would fail the app's
install rather than quietly ask for an old floor, and src/__tests__/templates.test.ts holds
every template to it. When bulma-ui releases on its own, published CLIs keep their floor, and
the next create-bestax release moves it. The docs sandboxes set the library's range themselves.
react and react-dom are declared dependencies too, with the library's peer ranges, though
nothing imports them either. npm installs a dependency's peers by itself, but Yarn 1 does not,
and without them yarn create bestax warned that the library's peers were unmet (#950). npm
installs the same packages either way. src/__tests__/package-manifest.test.ts fails when this
manifest leaves out a required peer of the installed library or gives one a range outside it, and
check:conformance --only=peer-ranges fails when a peer it declares carries anything but the
library's whole peer range, written the same way. Dependabot narrows these ranges when it bumps
react (#1012), so restore them on its PR; when the peer range itself moves, change them in a
fix(create-bestax) commit so the CLI releases with it.
Sync rules (this package re-ships other parts of the repo)
pnpm buildandprepackrunscripts/sync-skills.mjs, which copies every directory under the repo-rootskills/that holds aSKILL.mdinto the package. The roster is read, not listed (#540): every skill bundles by construction, with no allowlist to join. Full provenance (#385 vs #540) and the slot for a future per-skill opt-out live in that script's header. If such an opt-out is ever exercised, the docs pages that assert bundling — todaydocs/docs/skills/migrate.mdxanddocs/docs/skills/intro.md— must be corrected in the same change: no automated check reads those claims. What is not derivable is the prose rosters, this package'sCLAUDE_MDroster insrc/constants.tsamong them. Theskills-rosterconformance check holds every one of them to the directory in both directions;SKILL_ROSTERSinscripts/check-conformance.mjsis the authoritative list, and its failure names each file you missed. Never edit the bundled copy — changeskills/at the repo root; the build re-syncs.- A correction to a skill's content does not reach
npm create bestaxuntil this package itself releases.release.config.jsrefuses every commit scoped to something else ({ scope: '!(create-bestax)', release: false }), and the bundled copy undertemplates/skillsis a gitignored build artifact, so it carries no tracked diff that could trigger one. A fix landed asfix(bestax-migrate)therefore ships to that CLI's users and to the MCP server while scaffolded apps keep the old text until some unrelated create-bestax release comes along. When askills/change corrects something users would otherwise keep receiving, land afix(create-bestax)commit with it (#597). - The
CLAUDE_MDtemplate inconstants.tsis what every generated app tells its AI agents. When library conventions, skills, or the canonical docs entrypoint change (#203), check whether this template must change too. src/telemetry-core.tsis the shared consent/beacon kernel, duplicated byte-for-byte intobestax-migrate/src/telemetry-core.ts(standalone publishes, no bundler — so no workspace package). Edit the copy here, then copy it over migrate's;check:conformance --only=telemetry-corefails on any divergence. Tool-specific payload builders stay in each package'ssrc/telemetry.ts, and the worker's allowlists must gain new enum values FIRST (check:conformance --only=telemetry-allowlists) or events are silently dropped at ingest.- Templates pin the library's CSS import and icon setup — a change to bulma-ui's published
exports or flavors (
bestax.css,versions/*.css) may require a template update. templates/viteandtemplates/vite-tsfollow thereactandreact-tsstarters thatnpm create vite@latestwrites, Oxlint and its_oxlintrc.jsonincluded, and--lint eslintfollows what create-vite's--eslintwrites in their place (theESLINT_*constants insrc/constants.ts), and the compiler templates what itsreact-compilerstarters add (theREACT_COMPILER_*constants)..github/workflows/create-vite-drift.ymlrunsscripts/check-create-vite-drift.mjseach Monday and keeps an issue open while they differ from the create-vite release npm callslatest(node scripts/check-create-vite-drift.mjs --reportprints the same comparison). To catch up, scaffold both starters with and without--eslint, compare their tsconfigs, devDependencies,vite.configandsrc/mainwith the templates and the constants, and close the issue from the PR (#1049, #1304). The App, its assets, the README and_gitignorediffer on purpose, and the script doesn't compare them. TypeScript follows create-vite too: 7 under Oxlint, and 6 under ESLint, since typescript-eslint can't load 7 yet (#394). A file the catch-up adds or removes has to reach the docs sandboxes too, anddocs/scripts/sandbox.test.mjsfails until the files the StackBlitz project copies, with the ones it names as left out, are exactly the template's. The CodeSandbox project is a Create React App layout with files of its own, so a new template file that matters there is a change to its builder, and no test holds it to the template.templates/vite-tsis also what the docs site's StackBlitz and CodeSandbox buttons build from (docs/src/theme/CodeBlock/sandbox/, read at docs build time). The builders editsrc/main.tsxby string pattern, sodocs/scripts/sandbox.test.mjsruns them against the real template and fails if the bestax stylesheet import or the./App.tsximport moves, or a file they copy is renamed. Both install TypeScript 6 (SANDBOX_TYPESCRIPT) in place of the template's 7: StackBlitz's WebContainers can't run 7's nativetsc, and react-scripts loads the compiler API 7 doesn't ship.- The scaffolder edits the starter
Appwith string patterns, sosrc/__tests__/templates.test.tsruns every edit against the real templates. Under anoHelpersflavor each helper prop in the starter becomes a named class fromNO_HELPERS_STARTER_CLASSESinsrc/constants.ts; a helper prop added to the starter needs a row there, and that test fails until it has one. The icon step runs after that swap and writes into the sameApp, so what it inserts can use no helper prop at all; the test scans theAppboth steps leave behind. - An icon library's
packageVersionfollows the newest arm of bestax-bulma's peer range for it, not the newest release: on a 0.x package the caret holds the minor, so a pin past the peer range makes npm refuse the scaffold's install. The same test holds the two together.
Testing
- Unit:
pnpm --filter create-bestax test(Vitest). - E2E:
pnpm --filter create-bestax test:e2e(Playwright,e2e/— scaffolds real apps and boots them; seee2e/README.md). - Manual smoke: build, then scaffold outside the repo
(
node create-bestax/dist/index.js /tmp/app -t vite-ts -y) — inside the workspace you'd need--ignore-workspace.
Releases
Independent semantic-release keyed off the create-bestax commit scope
(release.config.js, tag create-bestax@x.y.z). It publishes with
pnpm publish, like every package here (#532) — the command, its flags, and the
ways that publish fails quietly are documented in VERSIONING.md and
scripts/lib/pnpm-publish.mjs.
Its prepack runs the guard and then scripts/sync-skills.mjs, so the skills
bundled into templates/ are refreshed as part of packing rather than
committed. There is no postpack because nothing is swapped out, only copied
in — a local pnpm pack therefore leaves templates/skills/ populated, which
is gitignored and expected.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

