meteor/meteor

---
title: Migrating to Meteor 3.0
description: How to migrate your application to Meteor 3.0.
---

> This guide will be created as we approach the Meteor 3.0 release.
> We're in the process of moving our documentation to Vitepress,
> and updating the Meteor API docs for version 3.0. For the latest updates,
> visit https://v3-docs.meteor.com/.

## What's the status of version 3.0?

**Latest version:** `3.0-rc.0` <br/>
**Node.js version:** `20.11.1 LTS` <br />
**NPM version:** `10.2.4`

Meteor 3.0, currently in its Release Candidate version, is approaching a recommendation for production use. You can check the "[Release 3.0 Pull Request](https://github.com/meteor/meteor/pull/12359)" to see what is being changed.

## How to prepare for version 3.0?

You can follow the guide "[How to migrate to Meteor Async in Meteor 2.x](/prepare-meteor-3.0.html)" to help you prepare your application for the new version by starting to use async methods.

## How to follow the progress on version 3?

The best way to follow the progress is by checking the "[What's left until an official Meteor 3.0?](https://github.com/meteor/meteor/discussions/12865)" discussion. We have also been sharing constant updates on [this topic](https://forums.meteor.com/t/fibers-public-roadmap-and-meteor-3-0/59627/84) in our forum.

## Frequently Asked Questions

### What is Fibers?

Meteor was designed at a time when callback hell was a development issue, so the team decided it at the time
to use [fibers](https://en.wikipedia.org/wiki/Fiber_(computer_science)) to make building applications much more straightforward with synchronous-looking code.
The Meteor fibers implementation is based on [node-fibers](https://github.com/laverdet/node-fibers), which is no longer supported as of NodeJS v16.0.0.

The main reason for this migration is to remove the dependency on fibers and make Meteor
compatible with the latest versions of Node.js.

For more information about fibers, you can check this [talk](https://www.youtube.com/watch?v=bxaOGDqVPKw)
from Ben Newman and this Stack Overflow [answer](https://stackoverflow.com/a/40865153/6688795).



### Will MongoDB Collection Methods be removed from the client?

No, we will not remove any MongoDB collection method from the client.

On the client side, all can remain the same. You can use both sync and async methods.
All should continue working as they are.

For example:

```js

// 2.x in the client side

const docs = MyCollection.find({ _id: '123' }).fetch();

// v3.0 in the client side

const docs = MyCollection.find({ _id: '123' }).fetch();

```
No changes are necessary. If you want to use the async methods to maintain isomorphic code, you can do it like this:

```js

// 2.x in the client side

const docs = MyCollection.find({ _id: '123' }).fetch();

// v3.0 in the client side, this will work anywhere

const docs = await MyCollection.find({ _id: '123' }).fetchAsync();

```

### Will MongoDB Collection Methods be removed from the server?

Yes, we will remove those MongoDB collection methods that do not end with `*Async`.

You can only use the methods with the `*Async` suffix on the server side.

For example:

```js
// 2.x in the server side

Meteor.methods({
  myMethod() {
    const doc = MyCollection.findOne({ _id: '123' });
  }
});


// v3.0 in the server side

Meteor.methods({
  async myMethod() {
    const doc = await MyCollection.findOneAsync({ _id: '123' });
  }
});
```

Methods that will be _only_ available in the *client* are:
  -`findOne`;
  -`insert`;
  -`remove`;
  -`update`;
  -`upsert`;

If you leave any code using one of these methods in the server side, you will get an error,
like this one below:

```bash
findOne is not available on the server. Please use findOneAsync instead.
```

### How to test Meteor 3.0?

You can create a new Meteor 3.0 project by running the command below:

```bash
meteor create my-new-project --release 3.0-rc.0
```

or you can use

```bash
npx meteor@beta
```
it will install the latest beta version of Meteor, please be sure that you are using Node v20 or higher globally.

### How to update from version 2?

You can update your Meteor 2.x project by running the command below inside your project folder:

```bash
meteor update --release 3.0-rc.0
meteor reset #resets local DB and project to a fresh state
```

### When will Meteor 3.0 be ready?

The Release Candidate version has been released. The official version's release will heavily depend on user feedback, but our goal is to release it in Q2 2024.


### How do I migrate my package to be compatible with Meteor 3.0?

For the packages that are client only
or that are do not using Meteor packages that will become async
or are already using `async` & `await` pattern.

The migration will look like this:

```js
// in you package.js
Package.onUse((api) => {
  api.versionsFrom(['1.10', '2.3', '3.0-rc.0']);
  //                               ^^^^^^^ for testing your package with meteor 3.0

  api.versionsFrom(['1.10', '2.3', '3.0']);
  //                              ^^^^^^^ for meteor 3.0

```
Then you can publish your package and test it with Meteor 3.0.

If in your package you are using Meteor packages that will become async,
you will need to migrate your package to use `async` & `await` pattern.

For concrete examples you can check a few examples of packages that have been in the works
of migrating to Meteor 3.0:

-   [`quave:migrations`](https://github.com/quavedev/meteor-migrations/pull/1)
-   [`percolate:synced-cron`](https://github.com/percolatestudio/meteor-synced-cron/pull/149)
-   [`react-meteor-accounts`](https://github.com/meteor/react-packages/commit/96313a1afcc41ef9a23c7496470b375e7d357793)
-   [`mdg:seo`](https://github.com/meteor/galaxy-seo-package/commit/8a30b32688df40e62ce434475dd3ee931dedf2b3)

You can follow a more in depth guide on how to migrate your package to be compatible with Meteor 3.0 [here](/prepare-meteor-3.0#Changes-for-packages).

### When will React packages for Meteor be ready for version 3.0?

We consider React packages to be ready.

It is important to note that migrating your front-end code to async is unnecessary.
You can still use the sync methods on the client side.

But to maintain isomorphic code, you can use the async methods on the client side.

In those cases, we have implemented `suspense` hooks so that you can use the async methods.

For example:

```js

// you can write like this:

import { useTracker, useSubscribe } from 'meteor/react-meteor-data'
function Tasks() {
  const isLoading = useSubscribe("tasks");
  const { username } = useTracker(() => Meteor.user())
  const tasksByUser = useTracker(() =>
          TasksCollection.find({username}, { sort: { createdAt: -1 } }).fetch()
  );


if (isLoading()) {
  return <Loading />
}

  // render the tasks
}


// or like this:

import { useTracker, useSubscribe } from 'meteor/react-meteor-data/suspense'
function Tasks() { // this component will suspend
  useSubscribe("tasks");
  const { username } = useTracker("user", () => Meteor.userAsync())
  const tasksByUser = useTracker("tasksByUser", () =>
          TasksCollection.find({username}, { sort: { createdAt: -1 } }).fetchAsync()
  );


  // render the tasks
}

```

`useFind` in the client will remain the same.

You can check the [react-meteor-data docs](https://github.com/meteor/react-packages/tree/master/packages/react-meteor-data) for more information
and these blog posts [part 1](https://dev.to/grubba/making-promises-suspendable-452f) [part 2](https://dev.to/grubba/new-suspense-hooks-for-meteor-3ddg) for a in-depth look on how we made those changes.


### When will Blaze be ready for version 3.0?

The team considered Blaze adjustments to version 3.0 almost done.

It is important to note that migrating your front-end code to async is unnecessary.
You can still use the sync methods on the client side.

But to maintain isomorphic code, you can use the async methods on the client side.

Since this [PR](https://github.com/meteor/blaze/pull/413) was released with Blaze 2.7. Blaze supports async in their views.

You can check the [Blaze docs](https://www.blazejs.org/api/spacebars#Async-states) for
more information on how to handle async states.

[@radekmie](https://github.com/radekmie) made two great posts about making Blaze async. Both are worth reading:
  - [On Asynchronicity in Blaze](https://radekmie.dev/blog/on-asynchronicity-in-blaze/);
  - [On Asynchronicity in Blaze (again)](https://radekmie.dev/blog/on-asynchronicity-in-blaze-again/);


### When will XYZ package be ready for version 3.0?

Meteor core packages are the responsibility of Meteor Software and are all being migrated.
If you encounter issues with any of them, let us know, please [open an issue](https://github.com/meteor/meteor/issues/new/choose) in our [repo](https://github.com/meteor/meteor).

This is the [list of all core packages](https://docs.meteor.com/packages/packages-listing.html).

Following the official release of Meteor 3.0, we plan to add new packages to the core and migrating them to Meteor 3.0.

For those packages that are not in the core but are maintained by the [community](https://github.com/Meteor-Community-Packages),
we hope that the community can work on them, but if for some reason that is not possible,
you can always ping us on [Slack](https://join.slack.com/t/meteor-community/shared_invite/zt-28aru814j-AwswQGt2D1xIXurvmtJvug) or in the [Forums](https://forums.meteor.com/).