bestax-migrate

bestax-migrate

Codemods that migrate existing React apps to @allxsmith/bestax-bulma — the actively maintained React component library for Bulma v1.

Currently supported sources:

Source	Status
react-bulma-components (v4)	✅ All 32 components mapped (a few patterns are flagged as TODOs)
rbx (v2)	✅ Full export surface mapped (a few patterns are flagged as TODOs)
bloomer (0.6)	✅ All 108 exports mapped (Font Awesome 4 icons and Bulma 0.4's Nav are flagged)
bulma-classes: Bulma's classes on plain JSX, no library	✅ Converts an element only when bestax renders the same markup; the rest is flagged

Pass the source as the first argument: bestax-migrate <source> <paths…>.

Requirements

Node.js 22 or newer. Node 18 and 20 are both past end-of-life. On an older runtime the CLI exits immediately with an explicit upgrade message.

This applies only to the Node version the codemod itself runs on. It places no requirement on the app being migrated — the source is read as text and is never executed.

Usage

# Preview what would change (no writes)
pnpm dlx bestax-migrate react-bulma-components src/ --dry
# …or, for an rbx or bloomer app
pnpm dlx bestax-migrate rbx src/ --dry
pnpm dlx bestax-migrate bloomer src/ --dry
# …or, for an app that writes Bulma's classes on plain JSX
pnpm dlx bestax-migrate bulma-classes src/ --dry

# Apply the migration
pnpm dlx bestax-migrate react-bulma-components src/

npm and yarn work too: npx bestax-migrate … / yarn dlx bestax-migrate ….

The codemod uses jscodeshift to:

• rewrite the source library's imports to @allxsmith/bestax-bulma (including destructuring and namespace imports)
• rename components and compound sub-components (Form.Textarea → TextArea, Card.Footer.Item → Card.FooterItem, Hero.Footer → Hero.Foot, …) — and, for bloomer, its flat names onto bestax's compounds (CardHeaderTitle → Card.Header.Title)
• convert props (renderAs → as, loading → isLoading, numeric spacing/text sizes → string unions, textAlign="center" → textAlign="centered", …)
• flatten responsive breakpoint objects (mobile={{ size: 4 }} → sizeMobile={4}) and bloomer's isDisplay/isHidden strings, arrays and objects (isHidden="touch" → visibilityTouch="hidden")
• for bulma-classes, turn raw Bulma markup into components and props (<a className="button is-primary"> → <Button as="a" color="primary">, <p className="has-text-centered mt-4"> → <Paragraph textAlign="centered" mt="4">), converting an element only when bestax renders exactly the same markup
• restructure patterns bestax models differently (Table.Container, Navbar dropdowns, Form.Help, icon-font children → <Icon name=…>)
• migrate stylesheets: CSS imports converge on @allxsmith/bestax-bulma/bestax.css, and SCSS files move from Bulma 0.9's @import + $var !default overrides to @use 'bulma/sass' with (…) plus @use '@allxsmith/bestax-bulma/scss/extras'
• update package.json: remove the source library, add @allxsmith/bestax-bulma, raise a declared pre-1.0 bulma to ^1 (adding it only when your sources import bulma/… directly — otherwise it arrives transitively), and swap the dead node-sass for dart sass (no install is ever run). Migrating rbx is what frees an app from Bulma 0.7.5: rbx pinned it as a direct dependency, so the app could not choose its own Bulma version at all. The four Bulma extensions rbx also pulled in (bulma-badge, bulma-divider, bulma-pageloader, bulma-tooltip) are reported rather than removed — bestax replaces all four, but a manifest entry is a deliberate declaration and your own Sass may import them. A bloomer app declared its own Bulma 0.6, which is what gets bumped. For bulma-classes there is no library to remove, and by default (--css keep) the app's Bulma version, Sass and stylesheet imports all stay: its own Bulma already styles every class a converted element renders. --css bestax or --css bulma moves it to Bulma v1 like the other sources

Anything without a safe automatic conversion is left in place with a // TODO(bestax-migrate): … comment, and the run ends with a report of every TODO by file and line. TODOs are expected output, not errors — resolve them with the migration guide (react-bulma-components, rbx, bloomer, Bulma classes), or let the bestax-migrate Agent Skill walk them for you:

npx skills add https://github.com/allxsmith/bestax --skill bestax-migrate

Options

Flag	Description
--dry, -d	Report what would change without writing files
--print, -p	Print transformed sources to stdout
--extensions, -e	File extensions to include (default js,jsx,ts,tsx,scss,sass)
--css <mode>	Stylesheet target: bestax, bulma, or keep (default bestax; keep for bulma-classes)
--no-deps	Skip updating package.json dependencies

After the codemod

• Run your package manager's install (the codemod rewrote package.json but never installs)
• Search for TODO(bestax-migrate) and resolve each comment
• Typecheck/build and review the rendered app

Full walkthrough: react-bulma-components migration guide · rbx migration guide · bloomer migration guide · Bulma classes migration guide.

Hardened by default

A codemod rewrites your source in place, so how it is built and published matters:

• Signed provenance — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the Provenance section on the npm page, or run npm audit signatures.
• npm OIDC trusted publishing — short-lived, per-run credentials; no long-lived NPM_TOKEN exists to be stolen. Release commits and tags are GPG-signed.
• Socket.dev scans every PR for malware, install scripts, obfuscated code, and privilege escalation before it can reach main.
• The libraries this tool migrates away from are never installed here — source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree.
• Dependencies are a deliberate act — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.
• Every GitHub Action is pinned to a full commit SHA, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity pnpm audit gate.
• Layered AI review before merge — CodeRabbit plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.

Full detail: SECURITY.md · Security guide

Telemetry

bestax-migrate can send one anonymous usage event after a successful run — only if you opt in when asked (once, on an interactive terminal). The event is just the run's shape — source library, CSS mode, the dry/deps flags, a capped changed-file count, and per-rule TODO counts — plus the CLI version, Node major version, and OS platform name. Never file paths, file contents, code, names, IPs, or machine IDs, and no identifier exists that could link two events together. Opt out any time with --no-telemetry, BESTAX_TELEMETRY=0, or DO_NOT_TRACK=1.

Full disclosure of every field and control: Telemetry guide

License

Source code licensed MIT