meteor-modern-build-stack

Modern build stack

The modern build stack is two independent tracks. Enable either or both.

1. Meteor Bundler Optimizations (Meteor 3.3+). One flag, SWC replaces

Babel, SWC minifier replaces Terser, @parcel/watcher replaces the legacy watcher, development skips legacy archs.

1. Rspack Bundler Integration (Meteor 3.4+). Atmosphere package

delegates app-code compilation to Rspack. Tree shaking, ESM, code splitting via HTTP, modern bundler plugins.

Standard current meteor create application skeletons ship both enabled. Purposefully small or compatibility-oriented skeletons, including minimal and legacy, may omit Rspack or the modern flag. Inspect the generated package.json and .meteor/packages instead of inferring features only from the Meteor version. For existing apps, enable optimizations first, then add Rspack once the app code is standards-clean.

Enable Meteor Bundler Optimizations

Add to package.json:

"meteor": {
  "modern": true
}

This enables SWC, the SWC minifier, the modern watcher, and dev-mode web arch skipping. Each falls back to legacy when something is incompatible, so this is backward compatible.

Opt out of pieces:

"meteor": {
  "modern": {
    "transpiler": false,
    "minifier": false,
    "watcher": false,
    "webArchOnly": false
  }
}

Or scope SWC: transpiler.excludeApp, transpiler.excludeNodeModules, transpiler.excludePackages, transpiler.excludeLegacy. Accept true or an array of paths/regexes.

Verbose transpiler logs to diagnose Babel fallbacks:

"meteor": {
  "modern": {
    "transpiler": { "verbose": true }
  }
}

Look for [Transpiler] Used Babel for <file> Fallback. The common cause is nested imports; see references/meteor-bundler-optimizations.md.

Enable Rspack integration

meteor add rspack

On first run the package installs the project-level Rspack setup. App code moves to Rspack; Meteor still handles Atmosphere packages and produces the final bundle. Requires entry points in package.json and no nested imports in app code. To migrate an existing app, use the migrate-to-rspack skill.

Inspect .meteor/versions, package.json, and the lockfile. Meteor 3.6-beta.0 pairs rspack@1.4.0-beta360.0, @meteorjs/rspack@3.0.0-beta.1 and Rspack 2.2.0; 3.5.2 retains the 1.3.0/2.2.0 integration pairing. See release pairings and 3.6 dependencies and workspaces. For Rspack 1-to-2 config migration, use migrate-to-rspack.

Scaffolds, PWA and offline behavior

For new-app skeleton selection or framework-neutral PWA/Workbox setup, read scaffolds and service workers. Meteor 3.6 (verified on 3.6-beta.0) adds separate --pnpm workspace and --pwa Blaze starters; neither converts an existing app. A worker caches shell/assets, not offline Meteor data. Existing bundler migrations remain owned by migrate-to-rspack.

SWC config files

.swcrc > swc.config.js > swc.config.ts

Only the first found is used. Use .swcrc for static config, swc.config.js for environment-driven config. The file name must be exactly .swcrc, not config.swcrc.

Install @swc/helpers to externalize SWC helpers (smaller bundles):

meteor npm install --save @swc/helpers

New apps ship with this preinstalled. Normally no further setup is needed; Meteor's pipeline detects it and emits imports instead of inlining. If only a production or legacy bundle fails on a helper import, inspect Rspack-generated and final Meteor output before changing .swcrc or adding manual imports.

Rspack config files

rspack.config.js | rspack.config.ts | rspack.config.mjs | rspack.config.cjs

Use defineConfig from @meteorjs/rspack. The function receives a Meteor parameter with build flags and helpers. See references/rspack-config.md for the full table and the most useful helpers (extendSwcConfig, compileWithRspack, compileWithMeteor, extendConfig, splitVendorChunk, persistDevFiles, disablePlugins, enablePortableBuild, setCache).

.meteorignore

Skip directories the bundler does not need to watch. Same syntax as .gitignore. Place at any depth; rules apply to the subtree.

docs/
design/
cypress/
scripts/
*.md
!README.md

For per-command rules, set the METEOR_IGNORE env var.

Do not copy .gitignore into .meteorignore blindly. Exclude unrelated large trees that Meteor does not need, but never match the active Rspack build context: Meteor consumes its generated main and test modules during final assembly.

Rspack also generates _build/, public/build-assets/, public/build-chunks/, and private/build-assets/. Include active suffixed variants such as build-assets-test and build-chunks-app-test on Meteor 3.5.2, plus custom context names. Add those paths to the native ignore configuration of recursive formatters, linters, typecheckers, test discovery, coverage, and IDEs. .gitignore alone is insufficient.

Minifier ownership

"modern": true selects Meteor's modern standard minifier. A third-party Atmosphere package that provides the JavaScript minifier remains part of the final Meteor assembly even when Rspack compiles app modules. Inventory custom minifier packages before migration. Keep or remove one only after comparing production output, source maps, build time, and runtime behavior.

Production legacy builds

Dev skips web.browser.legacy and web.cordova with "modern": true. Production still ships legacy by default. To drop legacy in production too, add modern to .meteor/platforms:

server
browser
modern

Memory limits

Rspack runs as a child process and may OOM on large apps. Raise the heap for tool processes temporarily when capturing evidence (Meteor 3.4.1+):

TOOL_NODE_FLAGS="--max-old-space-size=16384" meteor run

On Meteor 3.4.0, use NODE_OPTIONS="--max-old-space-size=16384".

First distinguish a one-shot build failure from growth during a long watch session. Audit large directories visible to Meteor and check the exact release for fixes. Test heap size and persistent cache as separate variables; revert a change that does not improve the failure or a measured memory trend.

Multiple instances

Meteor 3.5.2 separates development, normal test, and full-app test output within one context (_build/main-dev, _build/test, _build/app-test, plus mode-suffixed assets/chunks). This does not isolate Meteor caches, local Mongo, or ports. For separate local state or two instances of the same mode, use distinct ports and METEOR_LOCAL_DIR values; older integrations also need this for cross-mode output isolation:

PORT=3000 METEOR_LOCAL_DIR=.meteor/local-1 meteor run
PORT=3001 METEOR_LOCAL_DIR=.meteor/local-2 meteor run

Anti-patterns

• Enable optimizations and Rspack at the same time on a legacy app. Enable

"modern": true first, clean up Babel fallbacks, then add Rspack.

• Edit files inside _build/, public/build-assets/,

public/build-chunks/, or private/build-assets/. Autogenerated.

• Assume .gitignore prevents code-quality tools from scanning generated

Rspack output. Configure each tool's own ignore mechanism.

• Copy .gitignore to .meteorignore. Git may ignore Rspack's generated

handoff even though Meteor must read it.

• Remove a custom Atmosphere minifier only because Rspack is enabled.

Benchmark the final production bundle first.

• Disable Rspack persistent cache without need. It is the default and the

main rebuild-speed win. Disable only when investigating OOM or a cache-related Rspack bug.

• Name an SWC config config.swcrc or rc.swc. Only .swcrc is read.

See also

• references/meteor-bundler-optimizations.md
• references/rspack-config.md
• references/eval-cases.md
• For converting an existing app to Rspack: migrate-to-rspack skill.