migrate-to-rspack

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

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 .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 release without reviewing its paired dependencies and committing the authoritative lockfile. Validate a clean install and production build.

About this skill