How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/meteor/agent-skills --skill migrate-to-rspackBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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.


