migrate-to-meteor-3

Migrate a Meteor 2.x application to Meteor 3.x

Meteor 3 removed Fibers. Server-side Mongo APIs are async. The module system enforces strict mode. Client reactivity inside async code needs care. Atmosphere packages often need forking or replacement. Approach the migration in phases. Do not flip the framework version flag first.

Recommended strategy

For 3.6-beta.3 or 3.6-rc.0, prepare retained local data under the previous release before updating.

1. Update the project to the latest 2.x release.
2. Run the app with WARN_WHEN_USING_OLD_API=true meteor run. The console logs every sync-API call that needs an async sibling, giving you a to-do list before the framework flip.
3. Migrate server-side sync Mongo calls to *Async siblings while still on 2.x. Trace each changed function through every server-side caller: await where the caller consumes the value, forward Promises deliberately, and restructure sync-only boundaries. Stop only at an async-capable framework boundary. See references/async-rewrites.md and references/call-vs-callAsync.md. A community jscodeshift codemod automates the easy cases, but it misses non-standard collection imports (for example, meteor/<publisher>:collections). Review the diff by hand, then audit callback Promise ownership and collection argument shapes.
4. Audit Atmosphere packages. Find replacements or fork outdated ones; pin api.versionsFrom(['2.x', '3.0']). See references/package-triage.md. Save .meteor/versions and npm lockfile checkpoints so package-major changes remain distinguishable from Meteor.
5. Upgrade to the selected Meteor 3.x release.
6. Sweep implicit globals; rewrite to const or export / import. See references/module-system.md.
7. Audit Blaze helpers and Tracker.autorun blocks for lost reactivity after await. See references/client-reactivity.md.
8. Replace iterators that contain await (forEach, map, filter) with for...of or Promise.all. See references/js-iterators.md.
9. Audit publications using internal cursor APIs (_cursorDescription, manual sub.added) and framework handlers that read invocation this. Both synchronous and async publish handlers may return cursors; keep cursor transforms synchronous and use ordinary functions when Meteor must bind this. When a package patches Meteor.publish with an EnvironmentVariable, scope publish.call at the wrapper's top level, not inside the invoked handler. Verify invocation context before and after await. See references/publications.md and references/other-breaking-changes.md.
10. For TypeScript projects, inspect the target release and existing declaration provider. Keep working @types/meteor or zodern:types setups. Meteor 3.6-beta.1 adds explicit native opt-in through meteor types; earlier releases retain the legacy workflow. See references/typescript-migration.md, then use meteor-typescript for provider changes and checking.
11. For React projects, decide whether to adopt the Suspense-aware react-meteor-data import. See references/react-migration.md, then use meteor-react for current hook, scaffold, and build guidance.

Symptom router

Anti-patterns

• Do not run meteor update --release=3 first. Async-convert and package-triage on 2.x first.
• Do not global-replace findOne with findOneAsync. Many callers need rewriting, not just await.
• Do not mechanically rewrite client Minimongo calls to async. Both APIs work on the client. Prefer sync calls in naturally synchronous Blaze and Tracker code; use async calls in shared or already-async flows. Wrap reactive reads after an await with Tracker.withComputation.
• Do not rely on Iron Router controller naming-convention lookup. Pass controller: explicitly on every route.
• Do not mix await and .then() in the same function. Pick one.
• Do not assume implicit globals work. Every top-level identifier in 3.x must be const, let, or export-ed.
• Do not invent async replacements. Meteor.userId() remains synchronous inside methods and publications; there is no Meteor.userIdAsync().
• Do not use an arrow as a method or publication handler when it reads framework-bound this. An arrow ignores the invocation context Meteor supplies.
• Do not rewrite api.addFiles or api.export only because the app moved to Meteor 3. They remain supported for Atmosphere packages.

See also

• Async: async-rewrites.md, call-vs-callAsync.md, async-cheatsheet.md, js-iterators.md, removed-functions.md.
• Runtime: module-system.md, client-reactivity.md, publications.md, webapp-express.md, other-breaking-changes.md.
• Project: package-triage.md, typescript-migration.md, react-migration.md, eval-cases.md.
• Current Meteor React integration after the upgrade: meteor-react.

For requested case studies, read references/community-case-studies.md; use the symptom router for fixes.