mirror of
https://github.com/meteor/meteor.git
synced 2026-01-10 08:08:24 -05:00
point to vitepress migration guide
This commit is contained in:
Leonardo Venturini
@@ -22,5 +22,8 @@
|
||||
"clean": "hexo clean",
|
||||
"test": "npm run clean; npm run build",
|
||||
"start": "npm run build && chexo @meteorjs/meteor-hexo-config -- server"
|
||||
},
|
||||
"volta": {
|
||||
"node": "14.21.3"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -3,264 +3,4 @@ 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.2` <br/>
|
||||
**Node.js version:** `20.12.2 LTS` <br />
|
||||
**NPM version:** `10.5.0`
|
||||
|
||||
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.2
|
||||
```
|
||||
|
||||
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.2
|
||||
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.2']);
|
||||
// ^^^^^^^ 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/).
|
||||
Please visit [Meteor 3.0 Migration Guide](https://v3-migration-docs.meteor.com/) for our most up-to-date migration guide.
|
||||
|
||||
Reference in New Issue
Block a user