bestax-migrate

Files (14)

• SKILL.md
• component-map.md · references/bloomer/
• prop-map.md · references/bloomer/
• unmappables.md · references/bloomer/
• component-map.md · references/bulma-classes/
• prop-map.md · references/bulma-classes/
• unmappables.md · references/bulma-classes/
• css-migration.md · references/
• component-map.md · references/rbx/
• prop-map.md · references/rbx/
• unmappables.md · references/rbx/
• component-map.md · references/react-bulma-components/
• prop-map.md · references/react-bulma-components/
• unmappables.md · references/react-bulma-components/

SKILL.md (first lines)

# Migrating to bestax-bulma

`@allxsmith/bestax-bulma` is an actively maintained React library for **Bulma v1**. The
`bestax-migrate` codemod automates most of the conversion from an unmaintained predecessor;
this skill drives the codemod and finishes what it flags.

## Pick the source

The codemod's first argument names the library you are migrating _from_. Check the app's
`package.json` and imports:

| Source                                                                           | Argument                 | References                                                                                 |
| -------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
| `react-bulma-components` v4 (unmaintained since 2022, Bulma 0.9.x)               | `react-bulma-components` | [`references/react-bulma-components/`](references/react-bulma-components/component-map.md) |
| `rbx` v2 (abandoned 2019, pins Bulma **0.7.5** plus four extensions)             | `rbx`                    | [`references/rbx/`](references/rbx/component-map.md)                                       |
| `bloomer` 0.6 (archived 2018, Bulma 0.6 era, React 16 + `create-react-class`)    | `bloomer`                | [`references/bloomer/`](references/bloomer/component-map.md)                               |
| Raw Bulma classes on plain JSX (`<div className="box">`), no React Bulma library | `bulma-classes`          | [`references/bulma-classes/`](references/bulma-classes/component-map.md)                   |
| Static HTML pages or templates styled with Bulma (`<div class="box">`)           | `bulma-classes`          | [`references/bulma-classes/`](references/bulma-classes/unmappables.md)                     |

Everything below is written as `<source>`; substitute the argument from that table. The
reference paths follow the same split — `references/<source>/component-map.md`,
`prop-map.md`, `unmappables.md` — while
[`references/css-migration.md`](references/css-migration.md) is shared, because the stylesheet
work is about Bulma, not about which wrapper you came from.

## Workflow

Run these steps in order. Don't hand-convert what the codemod converts automatically.

1. **Dry-run the codemod** on the source directory and review the report:

   ```sh
   pnpm dlx bestax-migrate <source> src/ --dry
   ```

   For HTML pages, name a page, or walk a folder with `-e html` (`-e html,htm` for `.htm` pages
   too; a plain walk skips them,
   since most of it in a React project isn't a page to convert, and reports the Bulma pages it
   skipped as `html-file:not-included`):

   ```sh
   pnpm dlx bestax-migrate bulma-classes src/pages/login/index.html --dry
   pnpm dlx bestax-migrate bulma-classes -e html src/pages/ --dry
   ```

   Each page becomes a module beside it (`index.tsx`, or `.jsx` when the package isn't
   TypeScript) whose default export is `<Name>Page`, named from the file (its folder's for an
   `index.html`). The page stays as it was, and the codemod never writes over a module that's
   already there, so a re-run on the page writes nothing: after fixing a TODO, re-run on the
   module, which is what each TODO says. Its head, its `<html>` and `<body>` attributes and
   its scripts become `html-*` TODOs: put the app-wide parts in the app's `index.html` and
   entry, and port each script's work into the component. Under `--css bestax` or `--css bulma`
   the module imports the stylesheet in place of the page's Bulma `<link>`.

   A file that fails to parse or transform is marked `✖`, listed under `failed` in the report
   and left as it was, and the run exits 1 while every other file still converts. Fix that file
   and run the codemod on it again. TODOs alone leave the exit code at 0.

2. **Apply it** (same command without `--dry`), then run the project's formatter — the
   codemod preserves surrounding formatting but doesn't prettify what it rewrites.
   Besides the components, it also migrates **stylesheets** (CSS imports →
   `@allxsmith/bestax-bulma/bestax.css`; SCSS `@import 'bulma/bulma'` + `$var` overrides
   → `@use 'bulma/sass' with (…)` plus the bestax extras) and **package.json**.
   Flags: `--css bulma|keep` for other stylesheet targets, `--no-deps` to leave
   package.json alone. `bulma-classes` is the exception: it defaults to `--css keep`,
   because the app's own Bulma already styles every class it converts, so its stylesheets
   and Bulma version stay unless you pass `--css bestax` or `--css bulma`.

3. **Install** — the codemod edits package.json but never runs a package manager. Resolve the
   retained imports first: a component with no bestax equivalent keeps a trimmed,
   TODO-annotated import of the source library, which the manifest step has just removed — so a
   clean install leaves those unresolvable. The report names them in a `deps` entry.

   ```sh
   npm install   # or pnpm/yarn
   ```

   The report groups its entries by rule. `deps` covers every package.json edit —
   what was removed, added, or left for you to decide; `imports` covers a source
   import the codemod could not rewrite and left in place; `unsupported-file` names
   a file type it cannot parse (`.vue`, `.astro`) that still imports the source;
   `value-reference` marks a component used as a value rather than as JSX. Rules
   named `component:X` and `prop:y` are per-component and per-prop, and each is
   documented in the per-source `references/` pages.

   The report's `peer-deps` entries predict install failures: bestax-bulma needs
   **React 18/19** (react-bulma-components also ran on 17, while rbx and bloomer peer-depended
   on **React 16** — upgrade react/react-dom first) and its optional Font Awesome peer wants
   **FA ≥ 6.7** (an app pinned to FA 5 either upgrades or installs with
   `npm install --legacy-peer-deps`).

4. **Resolve every TODO**: `grep -rn "TODO(bestax-migrate)" src/`. Each comment names the
   prop/component and a hint. Recipes for every recurring case are in
   `references/<source>/unmappables.md`. Before writing a component by hand, look it up in
   `references/<source>/component-map.md` and its classes in `references/<source>/prop-map.md`:
   they name the component and the prop for each class, which the library's type declarations
   only tell you slowly. For form markup (`.field`, `.control`, inputs, selects), load the
   `bestax-form` skill too: it covers the label, `id` and help-text wiring. Delete each comment
   as you resolve it.

5. **Finish the stylesheet layer** — flagged Sass cases (computed variables,
   indented-syntax `.sass` files), CSS flavor choice, and Bulma 0.9→1 styling changes:
   follow [references/css-migration.md](references/css-migration.md).

6. **Finish**: typecheck/build, and review the rendered app side by side against the
   pre-migration UI.

## What the codemod handles vs. flags

Every export of every supported source has a mapping entry, held to that library's real export
surface by a coverage test. Imports (named, namespace, and destructuring), component renames,
prop renames and value conversions, breakpoint objects, CSS/SCSS stylesheet imports, and
package.json dependencies convert automatically.

It flags with `TODO(bestax-migrate)` instead of guessing: components with no bestax equivalent,
controlled APIs whose shape differs, breakpoints bestax has no prop for, dynamic prop values it
can't rewrite, and props with no counterpart. Files in formats it can't parse (`.astro`,
`.vue`, `.svelte`, `.mdx`) that import the source library are reported as `unsupported-file` —
migrate those by hand with the component map. Never "fix" a TODO by silencing it — convert the

From allxsmith/bestax, MIT.

More from allxsmith/bestax