migrate-to-rstack-cli

用途

Rstack CLI 是 rstack 包，通过 rs 二进制暴露。它为 Rstack JavaScript 工具链提供统一入口：一个 CLI、一个配置文件、一套一致的工作流。本技能用于在迁移场景下，把项目从独立使用的 Rsbuild、Rslib、Rstest、Rslint、Rspress、Prettier、sort-package-json、lint-staged、husky、lefthook 等工具切换到 Rstack CLI。

工具参考文档

编辑前先阅读每一份匹配的参考文档，并且只加载项目中实际存在的工具：

涉及 @rsbuild/core、rsbuild.config.*、rsbuild 命令或 Rsbuild 类型：rsbuild.md
涉及 @rslib/core、rslib.config.*、rslib 命令或 Rslib 类型：rslib.md
涉及 @rstest/core、@rstest/adapter-、rstest.config.、rstest 命令或测试导入：rstest.md
涉及 @rslint/core、rslint.config.*、rslint 命令或 lint 导入：rslint.md
涉及 prettier、package.json#prettier、.prettierrc*、prettier.config.*、.prettierignore、.editorconfig、sort-package-json、Prettier 插件或格式化脚本：prettier.md
涉及 @rspress/core、rspress.config.*、rspress 命令、主题或插件：rspress.md
涉及 lint-staged、nano-staged 及其配置：lint-staged.md
涉及 husky、.husky/、package.json#husky、lefthook、simple-git-hooks、.simple-git-hooks.* 或 Git hook 安装脚本：git-hooks.md

工作流程

检查清单文件、工作区目录（workspace catalogs）、锁文件、脚本、独立配置、忽略文件、Git hooks、TypeScript 类型与源码导入。
阅读匹配的参考文档，清点必须保留的行为：配置函数、CLI 参数、插件、预设、适配器、自定义配置路径以及链式命令。
检查最新 rstack 版本、Node.js engine、底层工具版本与相关 peer 范围。升级不兼容的插件或适配器；若不存在兼容版本则停止。确保开发与 CI 使用受支持的 Node.js 版本，但不要仅为满足 Rstack 而收窄已发布包的运行时 engines。使用现有包管理器把 rstack 添加为开发依赖。
如果匹配的参考文档使用了 define.* 注册方式，则创建 rstack.config.ts 并把独立配置迁移进去。
按参考文档的指示重写命令与导入。
再次搜索旧导入、二进制、配置路径、清单条目、包管理器元数据与类型引用。只有在排除直接使用、运行时使用以及未解决的 peer 约束之后，才移除相应条目。只有行为已在 rstack.config.* 中体现后，才删除独立配置。
使用仓库的包管理器刷新锁文件。确认预期的工具版本变化并解决 peer 依赖警告。
运行迁移后的脚本与仓库必需的检查。在相关时对比生成的产物或运行时行为。任何后续改动之后，针对最终代码重新运行相关检查。

Rsbuild、Rslib、Rstest、Rslint 与 Prettier 仍是 rstack 的传递依赖。从迁移范围内移除过时的直接依赖与导入；不要期望它们的名称从锁文件中消失。

忽略项清理

在迁移 lint 或格式化之后，若相同路径已被有效的 .gitignore 规则覆盖，则从 lint ignores 与 fmt 的 ignorePatterns 中移除这些排除项；两个命令都会自动读取 .gitignore。对于 fmt，还要从 ignorePatterns 中移除 package-lock.json 与 pnpm-lock.yaml；rs fmt 默认忽略它们。

保留必须作用于显式传入文件的否定规则与 fmt 排除项，因为显式传入文件会绕过 .gitignore。

组合检查

迁移 lint 与格式化命令后，在行为等价时优先使用更短的组合命令：

rs lint && rs fmt --check 优先写作 rs check
rs lint --type-check && rs fmt --check 优先写作 rs check --type-check

rs check 会保留这些 && 链的顺序与短路行为。

只组合具有相同工作目录、配置、作用范围与执行行为、且没有额外输入或命令专属选项的命令。给 rs check 传入共享的 -c 或 --config。

配置

配置文件

把每个工作区或配置根独立对待。当命令在不同包目录下运行时，monorepo 可能需要多个 Rstack 配置文件；请从每个目录验证配置发现是否正常。

使用以下默认名称之一：rstack.config.ts、.js、.mts 或 .mjs。

仅在自定义路径时使用 rs -c <path> 或 rs --config <path>。

// Configuration guide: https://rstack.rs/config
import { define } from 'rstack';

define.app({
  // Rsbuild config
});

define.test({
  // Rstest config
});

模块与导入

Rstack 在读取 rstack.config.* 时会加载所有顶层导入。当配置仅用于一个应用及其测试、一个库及其测试或一个文档站点时，优先使用静态导入。

如果同一份配置还包含 lint、格式化或暂存文件检查，则在相关的异步配置函数内部动态导入依赖，以避免在检查期间加载它们。把仅类型导入与 Node.js 内置导入保留在顶层。

define.app(async () => {
  const { pluginReact } = await import('@rsbuild/plugin-react');

  return {
    plugins: [pluginReact()],
  };
});

define.lint(({ js }) => [js.configs.recommended]);

define.lint 会向其配置工厂提供 @rslint/core API，因此无需手动导入。

Rstack 以原生 ESM 加载 TypeScript 配置。保留运行时可解析的文件扩展名，替换诸如 __dirname 之类的 CommonJS 全局变量。