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

Recommended strategy

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 Meteor 3.x.
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, install

    zodern:types

    and update

    tsconfig.json

    . See

    references/typescript-migration.md

    .
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

TypeError: Collection.findOne is not a function

references/async-rewrites.md

Method returns undefined

Promise

references/async-rewrites.md

Promise

references/async-rewrites.md

references/async-rewrites.md

$set

$push

references/async-rewrites.md

allow

deny

references/async-rewrites.md

Meteor.call

references/call-vs-callAsync.md

ReferenceError: X is not defined

references/module-system.md

references/module-system.md

references/module-system.md

{{> partial}}

references/module-system.md

references/client-reactivity.md

Promise

references/client-reactivity.md

transform

references/publications.md

sub.added

references/publications.md

this.userId

references/publications.md

references/package-triage.md

forEach

map

filter

await

references/js-iterators.md

WebApp.connectHandlers

references/webapp-express.md

references/webapp-express.md

rawCollection

references/other-breaking-changes.md

Meteor.userId()

references/other-breaking-changes.md

meteor reset

references/other-breaking-changes.md

Method stub (X) took too long

references/call-vs-callAsync.md

meteor update

references/other-breaking-changes.md

this.userId

references/other-breaking-changes.md

Meteor.publish

references/other-breaking-changes.md

meteor/*

any

references/typescript-migration.md

useTracker

useSubscribe

references/react-migration.md

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

  .

Further reading (optional)

references/community-case-studies.md