bestax-migrate

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install bestax-migrate
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 bestax-migrate。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

bestax-migrate 可帮助开发者将 React 应用迁移到 @allxsmith/bestax-bulma，这是一个持续维护的 Bulma v1 组件库。它支持从 react-bulma-components v4、rbx v2、bloomer 0.6，以及 JSX 中的原始 Bulma 类进行迁移。
此技能会引导 codemod 工作流程，说明针对不同来源的组件和 prop 映射，并协助解决每条 TODO(bestax-migrate) 注释，而不是留下不确定的转换结果。对于正在探索 Openclaw Skills 以维护前端的开发者，它提供了一条切实可行的路径，帮助从废弃的依赖迁移到经过审查且通过类型检查的 bestax 实现。

应用场景

用 bestax-bulma 替换不再维护的 React Bulma 库。
将使用静态 Bulma
className
值的普通 JSX 元素转换为 bestax 组件。
检查并解决现有的
TODO(bestax-migrate)
注释。
在安装前识别样式表、依赖、React peer 版本或 Font Awesome 兼容性问题。
使用针对来源的组件映射，手动迁移不支持的文件格式。

工作原理

检查 package.json 和导入内容，确定迁移来源：react-bulma-components、rbx、bloomer 或 bulma-classes。
在源目录上以 dry-run 模式运行 codemod，并检查其报告。
应用 codemod，然后格式化改写后的代码。根据来源和选项，它会更新组件、样式表和 package.json。
安装依赖并处理报告条目，包括保留的源导入、peer 依赖冲突、不支持的文件和数值引用。
搜索并解决每条 TODO(bestax-migrate) 注释，使用相关组件、prop 和不可映射项引用。加载 bestax-form 技能，处理表单标签、ID 和帮助文本的关联。
按照样式表迁移指南完成迁移，然后运行类型检查或构建，并将渲染后的 UI 与原始版本进行比较。

配置指南

根据应用的依赖和导入选择来源参数：
版本 4 使用 react-bulma-components
版本 2 使用 rbx
版本 0.6 使用 bloomer
JSX 中的原始 Bulma 类使用 bulma-classes
预览迁移：
pnpm dlx bestax-migrate src/ --dry
应用迁移并运行项目的格式化工具：
pnpm dlx bestax-migrate src/
安装依赖；codemod 会编辑 package.json，但不会调用包管理器：
npm install
如适用，请使用 pnpm install 或 yarn install。可选标志包括用于选择样式表处理方式的 --css bulma|keep，以及用于保持 package.json 不变的 --no-deps。对于 bulma-classes，默认值为 --css keep；也可使用 --css bestax 或 --css bulma 进行选择。检查 peer 依赖：bestax-bulma 要求 React 18 或 19，并可选支持 Font Awesome 6.7 或更高版本。

数据架构

此技能直接处理现有的 React 项目，不会定义单独的数据存储。codemod 可以改写源文件、样式表引用以及 package.json 中的依赖元数据。
工件或报告条目 用途
references//component-map.md 将来源库的组件映射到对应的 bestax 组件。
references//prop-map.md 记录来源 prop 和 class 到 bestax prop 的映射。
references//unmappables.md 为 codemod 无法安全转换的情况提供处理方案。
references/css-migration.md 提供 Bulma 样式表和 Sass 迁移的通用指南。
deps 报告 package manifest 变更和依赖决策。
imports 指出无法改写的来源导入。
unsupported-file 列出仍导入该来源的不支持格式，例如 .vue 或 .astro。
value-reference 标记作为值而非 JSX 使用的组件。
component:、prop: 或 kind:* 标识特定于组件、prop 或元素类型的转换规则和 TODO。
针对特定来源的参考资料按迁移来源整理。报告还会包含 peer-deps 预测信息，指出可能发生的安装冲突。

高级特性

支持命名导入、命名空间导入和解构导入、组件与 prop 重命名、值转换以及断点对象。
迁移 CSS 和 SCSS 导入，包括 Bulma Sass 变量覆盖，并可更新 package 依赖。
支持通过 --css bulma|keep 配置样式表目标，并通过 --no-deps 保留依赖。
bulma-classes
，可转换符合条件的静态 class 字符串以及受支持的
clsx
classnames
表达式，同时保留渲染标记必须保持不变的元素。
当组件、受控 API、断点、动态值或 prop 没有安全映射时，会添加 TODO，而不会猜测。
可在部分手动处理后安全地再次运行：库迁移只处理仍导入来源的文件；
bulma-classes
迁移会避免重复转换组件或重复添加已有 TODO。
报告不支持的格式以及潜在的 React 或 Font Awesome peer 依赖冲突，帮助开发者在完成迁移前规划清理工作。

name: bestax-migrate description: Migrate an existing React app to @allxsmith/bestax-bulma on Bulma v1, from raw Bulma CSS classes on plain JSX (className="button is-primary") or from an unmaintained React Bulma library (react-bulma-components v4, rbx v2, bloomer 0.6). Run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the per-source mapping references. Use when a React app styles its markup with Bulma classes and wants bestax components instead, when a repo imports react-bulma-components, rbx or bloomer, when TODO(bestax-migrate) comments are present in a codebase, or when asked to convert Bulma classNames to bestax-bulma.

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/
rbx v2 (abandoned 2019, pins Bulma 0.7.5 plus four extensions) rbx references/rbx/
bloomer 0.6 (archived 2018, Bulma 0.6 era, React 16 + create-react-class) bloomer references/bloomer/
Raw Bulma classes on plain JSX (
), no React Bulma library bulma-classes references/bulma-classes/

Everything below is written as ; substitute the argument from that table. The reference paths follow the same split — references//component-map.md, prop-map.md, unmappables.md — while 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.

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

pnpm dlx bestax-migrate src/ --dry

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.

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.

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).

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//unmappables.md. Before writing a component by hand, look it up in references//component-map.md and its classes in references//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.

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.

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 code per the references, or deliberately keep the old markup with className styling.

Source-specific headlines

react-bulma-components: all 32 v4 components are mapped. Element and Tile have no bestax equivalent; renderAs becomes as where supported.
rbx: migrating removes rbx itself — it pinned bulma@0.7.5 as a direct dependency plus bulma-badge, bulma-divider, bulma-pageloader and bulma-tooltip, so the app can finally choose its own Bulma version. rbx's badge and tooltip helper props become real wrapping / components. Its as is universal, bestax's is not. Because rbx pinned Bulma 0.7.5, you cross two Bulma majors — expect more visual drift than the 0.9 → 1 guide alone describes.
bulma-classes: there is no library to remove. An element converts only when the bestax component renders the same markup (tag, classes, attributes), so a converted page renders the same HTML; everything else stays as written, with a TODO when there is something to decide. Static class strings convert, and so does a clsx or classnames call of strings and conditional classes, where a condition on a flag becomes its prop (isLoading={busy}); any other computed className gets dynamic-class:, naming the component the element would become. Files a Next.js App Router may render as server components are left alone (rsc), and the manifest gains @allxsmith/bestax-bulma while the app's Bulma and stylesheets stay (the default --css keep). Its rules are kind: shaped; see references/bulma-classes/unmappables.md.
bloomer: every export is a flat name and most become dotted bestax compounds (CardHeaderTitle → Card.Header.Title). Most of its is* booleans already are bestax's (isActive becomes active where bestax names it so; isFullWidth becomes isFullwidth where bestax has the prop); the work is in isSize/isColor/isAlign (renamed per component), the isDisplay/isHidden helpers (flattened, arrays and objects included), tag (→ as where bestax has one) and render (always a TODO). Its icons are className-based and Font Awesome 4 — the biggest visual risk, see references/bloomer/unmappables.md. The app declared its own Bulma 0.6, which the codemod bumps; there is no pinned Bulma to free.

Rules

The codemod is safe to re-run after partial manual work: a library source only touches files that still import the library, and bulma-classes skips elements that are already components and never repeats a TODO it already wrote.
Don't downgrade converted props back to the old names; bestax uses is* booleans (isLoading), string size unions (textSize="4"), and as rather than renderAs.

If a component the app uses isn't in the component map, it wasn't part of that library's public API — check for a local wrapper component and migrate its internals instead.

AgentScope 测试夹具生成器

Bestax CSS Size Optimizer