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.

Prerequisite: Meteor 3.4+. Recommended before activation: enable "meteor": { "modern": true } and fix Babel fallbacks. For setup and helpers, use meteor-modern-build-stack.

Match @meteorjs/rspack to the Meteor release, not to @rspack/core or @rspack/cli:

The Atmosphere, Meteor npm integration, and Rspack core package versions are independent. Inspect .meteor/versions, package.json, and the lockfile. Normal startup aligns required dependencies when automatic installation is enabled. Review and commit those changes. Explicit meteor update --npm is an alternative, not an extra required step. Do not pair a newer integration major with an older Meteor release to copy a helper.

Already using Rspack? For the Meteor 3.6 beta upgrade, follow Rspack 1 to 2 and its toolchain checks. Keep valid entries/configuration; skip the first-activation steps below.

Decision flow

1. Does the app define client and server entry points in package.json

meteor.mainModule? If no, define them. Required.

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

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

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

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

1. Is the app server-only? Set only mainModule.server. Rspack still

bundles the server; client is skipped.

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

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

Required: no nested imports in app code

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

Three fixes:

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

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.

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

Old Meteor accepted import x from "some-cjs-lib" for a module.exports = ... package. Rspack + SWC do not by default. Two options:

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

Or restore interop in .swcrc:

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

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

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.

See also

• references/eval-cases.md
• For setup, helpers, and rspack.config.js API: meteor-modern-build-stack.