Meteor 3.x: what changed and how to migrate – a Practical Guide

Meteor has always been a framework focused on simplicity and productivity. With a single codebase, built-in real-time reactivity, and a closely linked package ecosystem, it offered a strongly unified approach that consistently paid off, especially for small teams trying to move fast without stitching together dozens of tools.

This approach held up well for a long time. But as the JavaScript ecosystem evolved, so did the expectations around performance, scalability, and modern asynchronous patterns. Meteor 3.x represents a turning point in that evolution. Rather than a routine upgrade, Meteor 3.x introduces foundational changes that modernize the platform and reshape some long-standing development patterns.

Every Meteor developer preparing for a 3.x upgrade has the same question: What exactly changed? What will break? And how do you migrate without disrupting a working application? These are practical questions that demand straightforward responses.

This guide explores the biggest changes in Meteor 3.x and walks through a practical migration from Meteor 2.x, covering what to update and how to approach the transition with confidence.

Why Meteor 3.x Matters?

Migrating to Meteor 3.x isn’t just about getting new features; it’s about keeping your application stable and up-to-date. Meteor 3.x updates the foundational functionality of the framework. Unlike earlier updates, this version introduces significant modifications to better align with today’s JavaScript ecosystem.

Meteor 3.x also improves runtime support, package compatibility, and overall performance. For developers using earlier versions, updating ensures that your app works properly with modern tools and libraries.

Who this guide is for

If you’ve built something with Meteor and you’re wondering what a 3.x upgrade actually means for your codebase, this is for you.

Perhaps you’re using Meteor 2.x and have been putting off upgrading since you’re unsure how much effort it will require. Maybe you’ve tried and encountered unexpected failure. Or possibly you simply want to know what has changed before touching anything. These are all valid concerns, and this guide is prepared to address them.

This is not a complete API reference or a guide for people who are new to Meteor. If you’re starting a completely new project, this guide may still be useful, but it’s mostly intended for individuals working with existing apps who want to upgrade them safely and without surprises.

What Changed in Meteor 3.x

Meteor 3.x includes several significant changes that impact how applications are written, run, and maintained. Unlike minor updates, these changes require developers, particularly those on lower versions, to modify parts of their codebase.

With Meteor 3.5 on the way, the framework continues to evolve rapidly, reinforcing the shift toward a more modern and future-ready development model. If you are still running Meteor 2.x applications, now is a good time to understand the 3.x migration path and start preparing for the transition.

Modern Node.js Support

Meteor 3.x uses modern Node.js, which means that any packages or code tied to older Node versions may need updating. Newer Node versions come with up-to-date security fixes and full support for modern JavaScript.

Fibers Removed and Async/Await Is Now Standard

Meteor 1.x and 2.x frameworks used Fibers under the hood to let developers write synchronous-style code for asynchronous operations without manually working with Promises, because Fibers wait for the database activity to finish before proceeding.

JavaScript

Meteor.methods({
  
  getUser() {
    const user = Meteor.users.findOne({
      _id: this.userId,
    });
    
    return user;
  },
});

Meteor.methods({
  
  getUser() {
    const user = Meteor.users.findOne({
      _id: this.userId,
    });
    
    return user;
  },
});

Now in Meteor 3.x, this is no longer possible. Fibers have been completely dropped because they’re incompatible with modern Node.js versions. All asynchronous Meteor APIs now return Promises, and you must use async/await or .then() to handle them.

JavaScript

Meteor.methods({

  async getUser() {

    const user = await Meteor.users.findOneAsync({
      _id: this.userId,
    });

    return user;
  },
});

Meteor.methods({

  async getUser() {

    const user = await Meteor.users.findOneAsync({
      _id: this.userId,
    });

    return user;
  },
});

Updated Packages and APIs

Key Meteor APIs and packages have been updated or replaced. A wide range of official Meteor packages have been updated to work with the new async model. This includes accounts-base, accounts-password, email, and others. Most of the changes follow the same pattern but each package has its own specifics worth reviewing before you migrate.

The old meteor/http is replaced by the fetch API, and methods like meteor.call and meteor.user now have async versions like callAsync and userAsync.

JavaScript

// Meteor 2.x
import { HTTP } from "meteor/http";

const result = HTTP.call("GET", url);

// Meteor 3.x
import { fetch } from "meteor/fetch";

const response = await fetch(url);
const data = await response.json();

// Meteor 2.x
import { HTTP } from "meteor/http";

const result = HTTP.call("GET", url);

// Meteor 3.x
import { fetch } from "meteor/fetch";

const response = await fetch(url);
const data = await response.json();

Ecosystem Alignment

By aligning with the broader ecosystem, Meteor 3.x ensures that your application isn’t stranded on old technology. You can tap into modern JS features like the Timer Promises API, optional chaining, async iterators, and tooling like ESLint configs, testing frameworks, and others, without special workarounds. Over time, this makes your codebase more adaptable and future-proof.

Before You Migrate: Pre-Upgrade Checklist

Upgrading to Meteor 3.x involves more than simply updating dependencies. Because of the migration to async/await and other breaking changes, it is critical to understand your codebase before making any changes.

Going in unprepared turns a simple improvement into a week of avoidable problems. A little careful planning can save you a lot of grief afterward.

Work through this checklist before you start.

Check Your Node.js Version

Don’t discover this problem halfway through the migration. As previously stated, Meteor 3.0 requires Node 20x, meteor 3.1 requires meteor 22, and meteor 3.5 will require Node.js 24. Run the command below in your terminal to confirm your node version is up to date.

Bash

node -v

node -v

Review Installed Packages

Not every package has been updated for Meteor 3.x. If you’re depending on a package that still relies on the old Fibers-based API, it will either break silently or throw errors at runtime.

Run this command to see what you’re working with:

Bash

meteor list

meteor list

Go through your Atmosphere and npm packages and ask yourself one simple question: if I removed this, would something break? If you can’t immediately answer that, it’s worth digging in.

Also, check the official Meteor migration guide for a list of packages that need to be updated or replaced when upgrading to 3.x.

Review Raw Mongo Usage

If your app uses direct Mongo operations outside standard Meteor collection methods, review them carefully. These areas deserve extra attention before migrating.

In Meteor 2.x, or older Meteor applications, you can interact directly with MongoDB through lower-level database access or custom server-side database logic. Meteor 3.x now uses defined asynchronous handling such as rawCollection(), rawDatabase() or direct database calls like insertOne(), updateOne(), findOne(), and aggregate().

Migrate Async-Compatible Code Early

One of the smartest ways to reduce migration complexity is to begin converting async-compatible code while your app is still running on Meteor 2.x.

Meteor 2.x already supports async/await in many situations, which means you can begin modernizing your code before upgrading the framework itself. This approach reduces migration pressure, helps reveal hidden async assumptions, and makes debugging easier.

Verify Tests and Critical Flows

If you have automated tests, run them now on your current 2.x codebase, or manually verify critical functionality such as:

Authentication
Publications and subscriptions
Database writes
Background jobs
Routing behavior

You want a reliable baseline. If tests are already failing before you start, you won’t know whether new failures are from the migration or pre-existing problems.

Create a Migration Branch or Backup

Before you make a single change to your codebase, protect yourself. Migrations most of the time go wrong. It happens more often than you’d think, so it’s best not to take chances without a safety net.

Set up a separate environment for migration testing.

If you don’t have a staging environment, this is a good moment to set up a simple clone of your production setup, with the same database structure and environment variables, but completely isolated. That way, you can run the migrated app without any risk.

Migrating Your Meteor 2.x App to 3.x: A Practical Walkthrough

In this section, we’ll walk through a simple, practical migration from Meteor 2.x to 3.x. The goal is to show what actually changes and how to fix it step by step.

Step 1: Complete the Pre-Upgrade Checklist

Before making any changes to Meteor itself, work through the Before You Migrate: Pre-Upgrade Checklist outlined earlier. This preparation phase helps identify compatibility issues, uncover Fiber-dependent code, and establish a safe baseline for the migration.

Step 2: Update Meteor and Packages

Run the command below in your project folder to update Meteor from 2.x to the latest version.

Bash

meteor update

meteor update

After a successful update, you will see a list of updated packages in your project terminal. If you’re using any community packages like aldeed:collection2 or ostrio:flow-router-extra, verify those separately.

Now, remove node_modules and pkg-lock.json from your application and update npm dependencies by running the command below:

Bash

meteor npm install

meteor npm audit

meteor npm install

meteor npm audit

When you run meteor npm audit, Meteor scans your installed npm packages and reports if there are vulnerable dependencies, severity levels (low, moderate, high, critical), and helps suggest fixes or updates. Ensure you fix any flagged vulnerabilities before moving forward.

Now, you’re ready to start migrating your code.

Step 3: Migrate Your Methods

Your Meteor methods file is where most of the migration work happens. Three things need to change across every method:

The method must be declared async.
Every database call must switch to its Async equivalent and be awaited.
this.userId and any other context properties must be captured into a local variable before any await call.

Here’s the pattern applied to a typical method in Meteor 2.x:

JavaScript

Meteor.methods({

  "resource.update"(id, data) {

    if (!this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    const resource = Collection.findOne(id);

    if (resource.userId !== this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    Collection.update(id, {
      $set: data,
    });
  },
});

Meteor.methods({

  "resource.update"(id, data) {

    if (!this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    const resource = Collection.findOne(id);

    if (resource.userId !== this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    Collection.update(id, {
      $set: data,
    });
  },
});

Here’s the updated version for Meteor 3.x.

JavaScript

Meteor.methods({

  async "resource.update"(id, data) {

    if (!this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    const userId = this.userId;
    const resource = await Collection.findOneAsync(id);

    if (resource.userId !== userId) {
      throw new Meteor.Error("not-authorized");
    }

    await Collection.updateAsync(id, {
      $set: data,
    });
  },
});

Meteor.methods({

  async "resource.update"(id, data) {

    if (!this.userId) {
      throw new Meteor.Error("not-authorized");
    }

    const userId = this.userId;
    const resource = await Collection.findOneAsync(id);

    if (resource.userId !== userId) {
      throw new Meteor.Error("not-authorized");
    }

    await Collection.updateAsync(id, {
      $set: data,
    });
  },
});

Apply this pattern to every method in your codebase.

Step 4: Migrate Your Publications

Publications in Meteor 3.x support async, but returning a cursor still works the same way for simple cases.

Here’s the pattern applied in Meteor 2.x:

JavaScript

Meteor.publish("resources", function () {

  if (!this.userId) {
    return this.ready();
  }

  return Collection.find({
    userId: this.userId,
  });

});

Meteor.publish("resources", function () {

  if (!this.userId) {
    return this.ready();
  }

  return Collection.find({
    userId: this.userId,
  });

});

Here’s the updated version for Meteor 3.x.

JavaScript

Meteor.publish("resources", async function () {

  if (!this.userId) {
    return this.ready();
  }

  return Collection.find({
    userId: this.userId,
  });

});

Meteor.publish("resources", async function () {

  if (!this.userId) {
    return this.ready();
  }

  return Collection.find({
    userId: this.userId,
  });

});

For simple cursor-returning publications like this, the only change made is adding async to the function declaration. The cursor return still works reactively as expected. More complex publications that manually call this.added(), this.changed(), and this.removed() will need more careful handling, but for the majority of publications, this is all you need.

Step 5: Migrate Client-Side Method Calls

On the client, Meteor.callAsync is now the preferred approach. The traditional callback-based approach is no longer the recommended pattern, and error handling moves into try/catch, which is cleaner and easier to follow.

Here is a sample code of Meteor 2.x:

JavaScript

Meteor.call("resource.update", id, data, (error, result) => {

  if (error) {
    console.error(error);
    return;
  }

});

Meteor.call("resource.update", id, data, (error, result) => {

  if (error) {
    console.error(error);
    return;
  }

});

Here is the updated code for Meteor 3.x:

JavaScript

try {
  const result = await Meteor.callAsync("resource.update", id, data);
  // handle result
} catch (error) {
  console.error(error);
}

try {
  const result = await Meteor.callAsync("resource.update", id, data);
  // handle result
} catch (error) {
  console.error(error);
}

Go through every Meteor.call in your client code and apply this pattern. It’s one of the most mechanical parts of the migration.

Step 6: Update Your Server Entry Point

If your server/main.js startup block contains any async operations, mark it async as shown in the code:

JavaScript

// meteor 3.x
Meteor.startup(async () => {
 // async operations are now safe here
});

// meteor 3.x
Meteor.startup(async () => {
 // async operations are now safe here
});

Step 7: Run and Verify

At this point, the migration steps are complete. Start the app by running the command:

Bash

meteor run

meteor run

If you have a test suite, run it, and if something is broken but there’s no error in the console, a missing await is always the first thing to check.

What improves after migration?

You’ve completed the migration to Meteor 3.x, and it’s a lot of work for an app that appears to be the same as before. So it’s worth taking a moment to be specific about what’s better on the other side because there are genuine, tangible benefits waiting for you once you get through it.

Here’s what gets better after migration:

Better Developer Experience
Better TypeScript Support
Easier Maintenance
Improved Performance and Stability
Better Compatibility with the JavaScript Ecosystem
Cleaner, Modern Async Code

Ecosystem & Tooling Updates

Some packages made it through the transition in perfect condition. Others did not make it. A couple of tools have actually gotten much better. Here’s how things stand.

The Atmosphere Package Ecosystem

The Atmosphere ecosystem changed significantly around the 3.x release. Many widely used packages have been updated, and the quality of those updates differs. Some packages were updated quickly by active maintainers, and some were picked up by community contributors.

If you are using official Meteor packages, they are generally well-maintained and updated to ensure compatibility. The main thing to verify is that each package is running on its latest version.

Here’s a quick status rundown on some of the most commonly used packages:

Package	Status for 3.x
ostrio:flow-router-extra	Updated
matb33:collection-hooks	Updated
percolate:migrations	Check for community fork
iron:router	Abandoned (migrate to FlowRouter)
accounts-base / accounts-password	Official (updated)
aldeed:collection2	Updated
aldeed:simple-schema	Updated
msavin:mongol	Check latest release

This table isn’t complete; always check the package’s current Atmosphere or Package Replacements guide before depending on it.

Meteor DevTools updates

If you’ve been using the Meteor DevTools Evolved extension during development, whether in Chrome or Firefox, for tasks like inspecting subscriptions, analyzing DDP traffic with filtering and search, monitoring method calls, visualizing Minimongo data, and tracking performance, there’s good news: it has been updated and is fully compatible with Meteor 3.x.

The extension gives you everything you need to track and understand what’s going on under the hood of your Meteor application.

Galaxy hosting compatibility

Since Galaxy is the official hosting platform for Meteor, it is typically updated alongside major releases. This means you can deploy Meteor 3.x applications without making serious changes to your deployment configuration. With full ongoing development, improvements, and feature additions. Galaxy is not just compatible with Meteor 3.x, it’s the version the platform is actively being built around.

Galaxy itself has also expanded in capability. In addition to application hosting, it now offers managed services such as MongoDB, PostgreSQL, and Redis directly within the platform. This can greatly simplify deployment and infrastructure management, especially for developers who previously relied on separate database providers. If you are currently managing external database services, integrating your infrastructure on Galaxy is a more effective alternative to consider.

Package Compatibility: Lessons from the Migration

After upgrading to 3.x in Meteor, one thing becomes clear: not all packages behave the same way.

Core packages worked smoothly with little to no changes, as expected. However, some third-party packages required updates, small fixes, or complete replacement, especially those that relied on older patterns like Fibers.

This is where preparation pays off. Knowing which packages fall into each category ahead of time can save hours during migration, but even after upgrading, it’s important to ensure everything is reliable and up to date.

FAQ

Can I migrate incrementally?

Yes, and for most apps it’s the recommended approach. You don’t have to migrate everything at once. A common strategy is to start with the server-side methods and database calls, the areas most directly affected by the async changes, and work outward from there.

What if a package I depend on hasn’t been updated yet?

First, check the community-maintained Package Replacements List. Someone may have already solved the problem. If the package is genuinely unmaintained, you have three practical options: find an npm equivalent that does the same job, look for a community fork on GitHub, or fork it yourself and make the async changes.

Is performance better or worse after migration?

Better, in most cases. Native async/await is how Node.js was designed to handle concurrency, and removing the Fibers layer means your server runs cleaner under load. Build times have also improved significantly in recent Meteor 3.x releases. Meteor 3.3 replaced Babel with the SWC transpiler, cutting build times by roughly 60%, and Meteor 3.4 introduced Rspack, bringing build times down by around 4x and bundle sizes down by 88%.

Should I consider migrating away from Meteor instead?

That’s a fair question to ask, and worth thinking through. If your app is small, stable, and not actively growing, the migration effort might be hard to justify in the short term. But if you’re building something you plan to maintain and grow, staying on Meteor 2.x is no longer a safe option. According to the Meteor supported versions clarification and transition timeline, Meteor 2.x reached End-of-Life in December 2025, not receiving updates since then.

As for moving away from Meteor entirely, the framework is in a healthier place than it has been in years, with active development, a growing community, and a roadmap that’s clearly pointed forward. Unless you have specific needs that Meteor fundamentally can’t meet, migrating to 3.x is a more practical option than rewriting your app from scratch in a different stack.

Do I need to update my database?

Possibly. Meteor 3.x ships with MongoDB driver 6.x, which requires MongoDB server version 5.0 or above. If you’re running an older MongoDB version, you’ll need to upgrade your database server as part of the process. For hosted databases on MongoDB Atlas, this is straightforward. For self-hosted MongoDB, test the upgrade carefully in a staging environment first.

What’s the best place to get help if I get stuck?

The Meteor Forums are the most active community resource; the migration has been well documented there, and chances are someone has already run into whatever problem you’re facing. The officialmigration guide is also comprehensive and regularly updated.

These articles can be helpful because they provide practical context and documentation. If you run into a problem, there is a good chance another developer has already documented a similar issue and how they resolved it.

Conclusion

Migrating to 3.x in Meteor is less about adding new features and more about modernizing how your application is built and maintained. It introduces important changes, especially the move to async/await and updates across the ecosystem, that require careful attention during upgrade.

While the migration can involve refactoring and dependency updates, the result is a cleaner, more modern codebase that aligns better with today’s JavaScript standards. Applications become easier to maintain, more compatible with modern tools, and better prepared for future updates.

In the end, the effort you put into migrating is an investment in stability and long-term sustainability.