Verwendung
- Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
- Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
- Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/meteor/agent-skills --skill migrate-to-rspackVor dem Start
- Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
- Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.
Migrate an existing app to Rspack
Rspack compiles app code; Meteor builds Atmosphere packages and assembles the bundle. Keep packages, but audit their architecture and browser dependencies.
Meteor 3.4+ required. Prefer enabling "meteor": { "modern": true } and fixing Babel fallbacks first. For setup/helpers, use meteor-modern-build-stack.
Match @meteorjs/rspack to the Meteor release, not to @rspack/core or @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. |
| 3.5.2 | 1.3.0 | 2.2.0 | Dependency diagnostics, mode isolation, full-app/TLA and cache fixes. |
| 3.6-beta.0 | 1.4.0-beta360.0 | 3.0.0-beta.1 | Rspack 2.2.0 and workspace-aware installs. |
| 3.6-beta.1 | 1.4.0-beta360.1 | 3.0.0-beta.2 | TypeScript rebuild-loop fix; Node 26.8.2. |
| 3.6-beta.3 | 1.4.0-beta360.3 | 3.0.0-beta.3 | Rspack 2.2.7; architecture graphs and test-ignore fixes. |
| 3.6-rc.0 | 1.4.0-rc360.0 | 3.0.0-rc.0 | Rspack 2 and separate architecture entries. |
Inspect .meteor/versions, package.json, and the lockfile: Atmosphere, Meteor npm integration and Rspack core versions are independent. With automatic installs enabled, startup aligns dependencies; review and commit the changes. meteor update --npm is an alternative. Keep the release pairing.
Already using Rspack? For the Meteor 3.6 beta or RC upgrade, follow Rspack 1 to 2 and its toolchain checks. Keep valid entries/configuration; skip the first-activation steps below.
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
importinside anif,
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 rspackand watch the verbose[Transpiler]log for
remaining (app) failures.
Required: entry points
{
"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.
For 3.6-beta.3 and RC separate legacy/native entries and earlier-version limits, read architecture preservation.
Required: no nested imports in app code
Apply the nested-import rewrites to app code. Adapt callers when using Promise-returning import(); Atmosphere package code stays on Meteor's bundler.
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:
{
"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 or METEOR_IGNORE. Rspack writes Meteor-facing entry modules there, then Meteor reads them to assemble the final bundle. Resolve renamed contexts before auditing ignores.
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 | SWC on the 3.6 beta pairing; earlier integrations retain Babel. See framework reference. |
zodern:types | Keep the working declaration provider during bundler migration; beta.1 native adoption is a separate explicit choice. |
Plugins acting only on Atmosphere package files can stay. Plugins acting on app-folder files (entry folder excluded) must move to Rspack.
CommonJS default-import interop
Prefer namespace imports. For the interop override and its app-wide CommonJS/tree-shaking cost, read references/code-migrations.md.
CI and Docker
Resolve required npm updates locally and commit package.json and the lockfile. Use the existing manager's frozen install with dev dependencies, then build. On rspack@1.3.0 (Meteor 3.5.2), meteor.autoInstallDeps: false still reports missing/outdated dependencies and manual commands; earlier opt-out behavior can skip those checks. Inspect the first dependency/config error and the actual project root before choosing a fix. See references/troubleshooting.md.
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
.swcrcto 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 release without reviewing its paired dependencies and committing
the authoritative lockfile. Validate a clean install and production build.
See also
references/eval-cases.md- For setup, helpers, and
rspack.config.jsAPI:meteor-modern-build-stack.


