migrate-to-rspack

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate an existing app to Rspack

将现有应用迁移至Rspack

Rspack compiles app code while Meteor builds Atmosphere packages and assembles the final bundle. Do not rewrite packages merely because Rspack is enabled, but audit their architecture declarations and browser-incompatible dependencies.

Prerequisite: Meteor 3.4+. Strongly recommended to enable

"meteor": { "modern": true }

first (Meteor 3.3+) and fix Babel fallbacks, then add Rspack. See the

meteor-modern-build-stack

skill for the activation knobs and

rspack.config.js

shape.

Match

@meteorjs/rspack

to the Meteor release, not to

@rspack/core

@rspack/cli

Meteor	`rspack`	`@meteorjs/rspack`	Capability boundary
3.4	`1.0.0`	`1.0.0`	Base integration and helpers.
3.4.1 and 3.5	`1.1.0`	`2.0.1`	Adds v2 helpers and inherited `TOOL_NODE_FLAGS` .
3.5.1	`1.2.0`	`2.1.0`	Revised client polyfills and extension discovery.

The Atmosphere, Meteor npm integration, and Rspack core package versions are independent. Inspect

.meteor/versions

package.json

, and the lockfile. After changing the Meteor release, run

meteor update --npm

, inspect the npm changes, and commit the dependency files. Do not pair a newer integration major with an older Meteor release only to copy a current helper.

Rspack负责编译应用代码，而Meteor负责构建Atmosphere包并组装最终bundle。不要仅仅因为启用了Rspack就重写包，而是要检查它们的架构声明和浏览器不兼容的依赖项。

前提条件：Meteor 3.4及以上版本。强烈建议先启用

"meteor": { "modern": true }

（Meteor 3.3及以上版本可用）并修复Babel回退问题，再添加Rspack。有关激活选项和

rspack.config.js

的结构，请查看

meteor-modern-build-stack

技能。

请将

@meteorjs/rspack

版本与Meteor版本匹配，而非与

@rspack/core

或

@rspack/cli

版本匹配：

Meteor版本	`rspack` 版本	`@meteorjs/rspack` 版本	功能边界
3.4	`1.0.0`	`1.0.0`	基础集成与辅助工具。
3.4.1 和 3.5	`1.1.0`	`2.0.1`	新增v2辅助工具及继承的 `TOOL_NODE_FLAGS` 。
3.5.1	`1.2.0`	`2.1.0`	优化客户端polyfill及扩展发现机制。

Atmosphere包、Meteor npm集成和Rspack核心包的版本相互独立。请检查

.meteor/versions

、

package.json

和锁文件。更改Meteor版本后，运行

meteor update --npm

，检查npm依赖变更并提交相关文件。不要仅为了复制当前辅助工具，就将较新的集成大版本与较旧的Meteor版本搭配使用。

Decision flow

决策流程

Does the app define client and server entry points in
```
package.json
```
```
meteor.mainModule
```
? If no, define them. Required.
Trace the client and client-test graphs. Do they reach CommonJS export assignments, Node built-ins, server-only local package entries, or missing generated inputs in a clean checkout? If yes, repair the boundary before activation. See
```
references/client-graph-preflight.md
```
.
Does the app code contain nested imports (ES
```
import
```
inside an
```
if
```
, function, or other block)? If yes, move them to top level or convert them to dynamic
```
import()
```
/
```
require
```
. Required for app code; OK in Atmosphere packages.
Does the app rely on a Meteor build plugin (
```
less
```
,
```
fourseven:scss
```
,
```
coffeescript
```
,
```
zodern:melte
```
,
```
jorgenvatle:vite
```
)? Plan an Rspack loader replacement and prove capability parity before removal. See
```
references/framework-and-css.md
```
.
Does the app rely on bare default imports from CommonJS packages (
```
import x from "some-cjs"
```
)? Decide between rewriting to
```
import * as x
```
or restoring Meteor-style interop in
```
.swcrc
```
. See
```
references/code-migrations.md
```
.
Is the app server-only? Set only
```
mainModule.server
```
. Rspack still bundles the server; client is skipped.
Does the app keep CSS or HTML outside its entry folder, or import app-local symlinks? Preserve the boundary with
```
meteor.modules
```
or
```
resolve.symlinks: false
```
; see the references.
Run
```
meteor add rspack
```
and watch the verbose
```
[Transpiler]
```
log for remaining
```
(app)
```
failures.

应用是否在
```
package.json
```
的
```
meteor.mainModule
```
中定义了客户端和服务器端入口点？如果没有，请定义它们。此步骤为必填项。
追踪客户端和客户端测试代码图。它们是否引用了CommonJS导出赋值、Node内置模块、仅服务器端的本地包入口，或者在干净检出时缺少生成的输入文件？如果是，请在启用Rspack前修复这些边界问题。请查看
```
references/client-graph-preflight.md
```
。
应用代码中是否包含嵌套导入（ES
```
import
```
语句位于
```
if
```
、函数或其他代码块内部）？如果是，请将其移至顶层，或转换为动态
```
import()
```
/
```
require
```
。应用代码中必须执行此操作；Atmosphere包中则无需修改。
应用是否依赖Meteor构建插件（
```
less
```
、
```
fourseven:scss
```
、
```
coffeescript
```
、
```
zodern:melte
```
、
```
jorgenvatle:vite
```
）？请规划使用Rspack loader替代，并在移除原插件前验证功能一致性。请查看
```
references/framework-and-css.md
```
。
应用是否依赖从CommonJS包中导入默认导出（
```
import x from "some-cjs"
```
）？请决定是重写为
```
import * as x
```
，还是在
```
.swcrc
```
中恢复Meteor风格的互操作。请查看
```
references/code-migrations.md
```
。
应用是否仅为服务器端应用？请仅设置
```
mainModule.server
```
。Rspack仍会打包服务器端代码；客户端代码将被跳过。
应用是否将CSS或HTML文件存放在入口文件夹之外，或者导入应用本地的符号链接？请使用
```
meteor.modules
```
或
```
resolve.symlinks: false
```
保留边界；请查看相关参考文档。
运行
```
meteor add rspack
```
，并查看详细的
```
[Transpiler]
```
日志，检查是否存在剩余的
```
(app)
```
代码失败情况。

Required: entry points

必填项：入口点

json

{
  "meteor": {
    "mainModule": {
      "client": "client/main.js",
      "server": "server/main.js"
    },
    "testModule": "tests.js"
  }
}

Without

mainModule

, Rspack has no entry. Meteor's eager-loading model does not apply: Rspack does not auto-discover modules. See

references/framework-and-css.md

for CSS and HTML routing.

json

{
  "meteor": {
    "mainModule": {
      "client": "client/main.js",
      "server": "server/main.js"
    },
    "testModule": "tests.js"
  }
}

没有

mainModule

的话，Rspack将没有入口。Meteor的预加载模型不再适用：Rspack不会自动发现模块。有关CSS和HTML的路由，请查看

references/framework-and-css.md

。

Required: no nested imports in app code

必填项：应用代码中禁止嵌套导入

javascript

// app code: NOT allowed under Rspack
if (condition) {
  import { a as b } from "./c";
  console.log(b);
}

Three fixes:

javascript

// 1. Move to top
import { a as b } from "./c";
if (condition) console.log(b);

// 2. Dynamic import (standardized, supported)
if (condition) {
  const { a: b } = await import("./c");
  console.log(b);
}

// 3. require (CommonJS interop)
if (condition) {
  const { a: b } = require("./c");
  console.log(b);
}

Diagnose with verbose mode and look for

(app)

files failing with

Error: 'import' and 'export' cannot be used outside of module code

(package)

failures are fine; Atmosphere packages are not bundled by Rspack.

javascript

// 应用代码：Rspack下不允许这样写
if (condition) {
  import { a as b } from "./c";
  console.log(b);
}

三种修复方案：

javascript

// 1. 移至顶层
import { a as b } from "./c";
if (condition) console.log(b);

// 2. 动态导入（标准化，受支持）
if (condition) {
  const { a: b } = await import("./c");
  console.log(b);
}

// 3. require（CommonJS互操作）
if (condition) {
  const { a: b } = require("./c");
  console.log(b);
}

通过详细模式诊断，查找带有

Error: 'import' and 'export' cannot be used outside of module code

错误的

(app)

文件。

(package)

代码的失败无需担心；Atmosphere包不由Rspack打包。

Required: reserve build folders

必填项：预留构建文件夹

The integration writes to

_build/

public/build-assets/

public/build-chunks/

private/build-assets/

. Auto-added to

.gitignore

. If the project already uses any of these names, rename in

package.json

json

{
  "meteor": {
    "buildContext": "build",
    "assetsContext": "assets",
    "chunksContext": "chunks"
  }
}

Do not edit any file under those folders. Exclude them from IDE indexing and from every recursive formatter, linter, typechecker, test-discovery, and coverage scan.

.gitignore

does not configure those tools.

Do not match the active build context in

.meteorignore

METEOR_IGNORE

. Rspack writes Meteor-facing entry modules there, then Meteor reads them to assemble the final bundle. Resolve renamed contexts before auditing ignores.

该集成会写入

_build/

、

public/build-assets/

、

public/build-chunks/

、

private/build-assets/

.gitignore

中。如果项目已使用其中任意名称，请在

package.json

中重命名：

json

{
  "meteor": {
    "buildContext": "build",
    "assetsContext": "assets",
    "chunksContext": "chunks"
  }
}

请勿编辑这些文件夹下的任何文件。将它们排除在IDE索引之外，同时排除在所有递归格式化工具、代码检查工具、类型检查工具、测试发现工具和覆盖率扫描工具之外。

.gitignore

不会配置这些工具。

请勿在

.meteorignore

或

METEOR_IGNORE

中匹配当前构建上下文。Rspack会在这些目录中写入面向Meteor的入口模块，然后Meteor读取这些模块来组装最终bundle。在检查忽略规则前，请先解决重命名上下文的问题。

Replacing build plugins

替换构建插件

Most app-file build plugins move to Rspack loaders. Prove capability parity before removal; make conflicting activation and removal one reversible change. See

references/framework-and-css.md

Old plugin	Replacement
`meteor/less`	`less-loader` . See `references/framework-and-css.md` .
`fourseven:scss`	`sass-loader` + `sass-embedded` . See refs. Skeleton in `meteor create --full` .
`meteor/coffeescript`	`coffee-loader` (optionally chained with `swc-loader` ).
`zodern:melte` (Svelte)	Official Rspack Svelte loader.
`jorgenvatle:vite` (Vue/Solid)	Native Rspack Vue/Solid loaders.
`babel-plugin-react-compiler`	Babel via Rspack loader on `.jsx` / `.tsx` ; SWC for everything else.
`zodern:types`	Still compatible. Keep it.

Plugins acting only on Atmosphere package files can stay. Plugins acting on app-folder files (entry folder excluded) must move to Rspack.

大多数应用文件构建插件可替换为Rspack loader。在移除原插件前，请验证功能一致性；将冲突的激活和移除操作作为一个可回滚的变更。请查看

references/framework-and-css.md

。

旧插件	替代方案
`meteor/less`	`less-loader` 。请查看 `references/framework-and-css.md` 。
`fourseven:scss`	`sass-loader` + `sass-embedded` 。请查看参考文档。 `meteor create --full` 中包含示例骨架。
`meteor/coffeescript`	`coffee-loader` （可选择与 `swc-loader` 链式使用）。
`zodern:melte` （Svelte）	官方Rspack Svelte loader。
`jorgenvatle:vite` （Vue/Solid）	原生Rspack Vue/Solid loader。
`babel-plugin-react-compiler`	通过Rspack loader在 `.jsx` / `.tsx` 文件上使用Babel；其他文件使用SWC。
`zodern:types`	仍兼容，请保留。

仅作用于Atmosphere包文件的插件可保留。作用于应用文件夹文件（入口文件夹除外）的插件必须替换为Rspack loader。

CommonJS default-import interop

CommonJS默认导入互操作

Old Meteor accepted

import x from "some-cjs-lib"

for a

module.exports = ...

package. Rspack + SWC do not by default. Two options:

javascript

// preferred: switch to namespace import
import * as x from "some-cjs-lib";

Or restore interop in

.swcrc

json

{
  "module": {
    "type": "commonjs",
    "noInterop": false,
    "importInterop": "node"
  }
}

This emits CommonJS, defeating tree-shaking and static analysis app-wide. Migrate imports instead unless you cannot.

旧版Meteor允许对

module.exports = ...

的包使用

import x from "some-cjs-lib"

语法。而Rspack + SWC默认不支持此语法。有两种选择：

javascript

// 推荐：切换为命名空间导入
import * as x from "some-cjs-lib";

或者在

.swcrc

中恢复互操作：

json

{
  "module": {
    "type": "commonjs",
    "noInterop": false,
    "importInterop": "node"
  }
}

这会生成CommonJS代码，破坏整个应用的树摇优化和静态分析能力。除非万不得已，否则请迁移导入语句。

CI and Docker

CI与Docker

After upgrading Meteor locally, the required npm bumps must be committed. If they are not, CI/Docker builds fail with:

text

Could not find rspack.config.js, rspack.config.ts, rspack.config.mjs, or rspack.config.cjs

Preferred reproducible flow:

Run
```
meteor update --npm
```
locally after changing the Meteor release.
Commit
```
package.json
```
and the lockfile.
Run
```
meteor npm ci
```
followed by
```
meteor build
```
in CI.

See

references/troubleshooting.md

for the recovery-only Docker fallback when a pipeline intentionally repairs missing npm bumps during the build.

在本地升级Meteor后，必须提交所需的npm依赖更新。如果未提交，CI/Docker构建会失败并提示：

text

Could not find rspack.config.js, rspack.config.ts, rspack.config.mjs, or rspack.config.cjs

推荐的可复现流程：

更改Meteor版本后，在本地运行
```
meteor update --npm
```
。
提交
```
package.json
```
和锁文件。
在CI中运行
```
meteor npm ci
```
，然后执行
```
meteor build
```
。

当流水线需要在构建过程中自动修复缺失的npm依赖更新时，请查看

references/troubleshooting.md

中的Docker回退方案。

Anti-patterns

反模式

Add Rspack before fixing Babel fallbacks. Find them with
```
"meteor": { "modern": { "transpiler": { "verbose": true } } }
```
and fix them while still on the optimization-only stack.
Restore CJS interop globally in
```
.swcrc
```
to avoid migrating a handful of imports. Trades real bundle-size wins for short-term convenience.

Commit

_build/

public/build-assets/

public/build-chunks/

private/build-assets/

. Autogenerated.

Change the Meteor release without running
```
meteor update --npm
```
and committing its npm dependency changes. A stale lockfile makes clean CI builds fail or pick an incompatible integration major.

在修复Babel回退问题前就添加Rspack。可通过
```
"meteor": { "modern": { "transpiler": { "verbose": true } } }
```
找到这些问题，并在仍处于仅优化栈时修复它们。
在
```
.swcrc
```
中全局恢复CJS互操作，以避免迁移少量导入语句。这是以牺牲真实的包体积优化为代价换取短期便利。

提交

_build/

、

public/build-assets/

、

public/build-chunks/

、

private/build-assets/

目录。这些是自动生成的文件。

更改Meteor版本后，未运行
```
meteor update --npm
```
并提交npm依赖变更。过时的锁文件会导致干净的CI构建失败，或选择不兼容的集成大版本。

另请参阅

```
references/code-migrations.md
```
```
references/client-graph-preflight.md
```
```
references/validation-matrix.md
```
```
references/framework-and-css.md
```
```
references/troubleshooting.md
```
```
references/eval-cases.md
```

For setup, helpers, and

rspack.config.js

API:

meteor-modern-build-stack

```
references/code-migrations.md
```
```
references/client-graph-preflight.md
```
```
references/validation-matrix.md
```
```
references/framework-and-css.md
```
```
references/troubleshooting.md
```
```
references/eval-cases.md
```
如需设置、辅助工具和
```
rspack.config.js
```
API相关内容，请查看
```
meteor-modern-build-stack
```
。

migrate-to-rspack

Original

Translation

Migrate an existing app to Rspack

将现有应用迁移至Rspack

Decision flow

决策流程

Required: entry points

必填项：入口点

Required: no nested imports in app code

必填项：应用代码中禁止嵌套导入

Required: reserve build folders

必填项：预留构建文件夹

Replacing build plugins

替换构建插件

CommonJS default-import interop

CommonJS默认导入互操作

CI and Docker

CI与Docker

Anti-patterns

反模式

See also

另请参阅