github/meteor
1
1
Fork 0
mirror of https://github.com/meteor/meteor.git synced 2026-01-10 08:08:24 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve the structure of the migration guide.

Browse Source
This commit is contained in:
Frederico Maia
2024-04-22 18:10:48 -03:00
parent 9f1aa821f3
commit 8846824155
7 changed files with 158 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
v3-docs/v3-migration-docs/.vitepress/config.mts
View File

@@ -2,17 +2,22 @@ import { defineConfig } from "vitepress";
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "Meteor V3 Migration Guide",
description: "Meteor.js Migration Guide to v3",
title: "Meteor 3.0 Migration Guide",
description: "Guide on migrating from Meteor 2.x to Meteor 3.0",
lang: 'en-US',
head: [["link", { rel: "icon", href: "/logo.png" }]],
lastUpdated: true,
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [
{ text: 'Meteor 3.0 Docs', link: 'https://v3-docs.meteor.com' },
],
sidebar: [
{
text: "Guide",
items: [
{text: "Overview", link: "/"},
{text: "Frequently Asked Questions", link: "/frequently-asked-questions/"},
{text: "Breaking Changes", link: "/breaking-changes/"},
{text: "Meteor.call x Meteor.callAsync", link: "/breaking-changes/call-x-callAsync"},
{text: "Upgrading packages", link: "/breaking-changes/upgrading-packages"},
@@ -29,12 +34,12 @@ export default defineConfig({
{
text: "Front end",
items: [
{text: "React", link: "/front-end/react"},
{text: "Blaze", link: "/front-end/blaze"},
{text: "React Changes", link: "/front-end/react"},
{text: "Blaze Changes", link: "/front-end/blaze"},
]
},
{
text: "Migrating in 2.x",
text: "Migrating to Async in v2",
link: "/how-to-migrate/index"
}
],

2
v3-docs/v3-migration-docs/api/async-functions.md
View File

@@ -1,5 +1,5 @@
# Async Functions
# Using Async Functions
Meteor now uses the `Promise` [API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for all asynchronous operations.

117
v3-docs/v3-migration-docs/frequently-asked-questions/index.md Normal file
View File

@@ -0,0 +1,117 @@
# 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)) (coroutines) 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).
## What is the Meteor v3 release schedule?
Our current plan is to release Meteor v3 until Q2 2024. This is subject to change as we progress through the development of Meteor v3.
## 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? {#mongo-methods-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.
```
## When will React packages for Meteor be ready for version 3.0?
We consider React packages to be ready.
You can check more information on the [react page](./front-end/react.md).
## When will Blaze be ready for version 3.0?
The team considered Blaze adjustments to version 3.0 done, version 2.9 and upper are with all features regarding async APIs.
You can check more information on the [Blaze page](./front-end/blaze.md).
## 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).
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/).
Following the official release of Meteor 3.0, we plan to add new packages to the core and migrating them to Meteor 3.0.

2
v3-docs/v3-migration-docs/front-end/blaze.md
View File

@@ -1,4 +1,4 @@
# Blaze changes
# Blaze Changes
:::tip

2
v3-docs/v3-migration-docs/front-end/react.md
View File

@@ -1,4 +1,4 @@
# React changes
# React Changes
:::tip

4
v3-docs/v3-migration-docs/how-to-migrate/index.md
View File

@@ -1,4 +1,6 @@
# How to migrate to Meteor 3.0 in 2.x
# Migrating to Async in Meteor 2.x
In Meteor 3.0, we're transitioning from using Fibers to asynchronous methods and operations, aligning with community standards. While Fibers, our promise solution, was used in version 2.x, it's not supported from Node 16 onwards. We are now adopting `async` and `await` for better compatibility.
## Prerequisites

171
v3-docs/v3-migration-docs/index.md
View File

@@ -1,131 +1,17 @@
# Migrating to Meteor v3
This guide is a livid document where we will be documenting the process of migrating to Meteor v3.
This guide will be updated as we progress through the development of Meteor v3.
# Meteor 3.0 Migration Guide
> This guide is a live document outlining the migration to Meteor v3, which will be updated as development progresses.
This guide is for users with Meteor 2.x projects understand the changes between Meteor 2.x and Meteor 3.0. It's not required to read this guide before starting with Meteor 3.0. To learn Meteor 3.0, we recommend reading the [new documentation](https://v3-docs.meteor.com).
## What's the status of version 3.0?
Meteor 3.0 is currently in its Release Candidate (RC) phase, a nearly final version ready for final testing ahead of the official launch.
**Latest version:** `3.0-rc.0` <br/>
**Node.js version:** `20.11.1 LTS` <br/>
**NPM version:** `10.2.4`
## How to prepare for version 3.0?
You can follow the guide "[How to migrate to Meteor Async in Meteor 2.x](https://guide.meteor.com/prepare-meteor-3.0)" to help you prepare your application for the new version by starting to use async methods.
## What this guide will cover
This guide will try to cover the topics needed to migrate your application to Meteor v3. We will cover the following topics:
- [Breaking Changes](./breaking-changes/index.md), an overview of the changes that will affect your application.
- [Meteor.call x Meteor.callAsync](./breaking-changes/call-x-callAsync.md), why should you change your methods to use `Async` methods.
- [Upgrading packages](./breaking-changes/upgrading-packages.md), how to upgrade your packages to the be compatible with Meteor v3.
- [How async functions work and how to use them](./api/async-functions.md), a how-to guide in how to use async functions and helpers for Meteor.
- [Renamed Functions](./api/renamed-functions.md), a list of functions that were renamed in Meteor v3.
- [Removed Functions](./api/removed-functions.md), a list of functions that were removed in Meteor v3.
- [React in Meteor v3](./front-end/react.md), how to migrate your react code to Meteor v3
- [Blaze in Meteor v3](./front-end/blaze.md), how to migrate your blaze code to Meteor v3
- [How to migrate to Meteor 3.x in 2.x](./how-to-migrate/index.md), how can you migrate your application to Meteor v3 while in 2.x.
## 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).
## What is the Meteor v3 release schedule?
Our current plan is to release Meteor v3 until Q2 2024. This is subject to change as we progress through the development of Meteor v3.
## 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? {#mongo-methods-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:
@@ -143,30 +29,23 @@ meteor update --release 3.0-rc.0
meteor reset #resets local DB and project to a fresh state
```
## What this guide will cover
## When will React packages for Meteor be ready for version 3.0?
This guide will try to cover the topics needed to migrate your application to Meteor v3. We will cover the following topics:
We consider React packages to be ready.
You can check more information on the [react page](./front-end/react.md).
- [Frequently Asked Questions](./frequently-asked-questions/index.md), answers to common questions.
- [Breaking Changes](./breaking-changes/index.md), an overview of the changes that will affect your application.
- [Meteor.call x Meteor.callAsync](./breaking-changes/call-x-callAsync.md), why should you change your methods to use `Async` methods.
- [Upgrading packages](./breaking-changes/upgrading-packages.md), how to upgrade your packages to the be compatible with Meteor v3.
## When will Blaze be ready for version 3.0?
- [How async functions work and how to use them](./api/async-functions.md), a how-to guide in how to use async functions and helpers for Meteor.
- [Renamed Functions](./api/renamed-functions.md), a list of functions that were renamed in Meteor v3.
- [Removed Functions](./api/removed-functions.md), a list of functions that were removed in Meteor v3.
The team considered Blaze adjustments to version 3.0 done, version 2.9 and upper are with all features regarding async APIs.
- [React in Meteor v3](./front-end/react.md), how to migrate your react code to Meteor v3
- [Blaze in Meteor v3](./front-end/blaze.md), how to migrate your blaze code to Meteor v3
You can check more information on the [Blaze page](./front-end/blaze.md).
## 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).
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/).
Following the official release of Meteor 3.0, we plan to add new packages to the core and migrating them to Meteor 3.0.
- [How to migrate to Meteor 3.x in 2.x](./how-to-migrate/index.md), how can you migrate your application to Meteor v3 while in 2.x.
## External links
@@ -177,15 +56,15 @@ Currently we are aware of the following community migration guides:
### Videos
Migrating apps to Meteor 3.0:
- TicTacToe & others - [YouTube](https://www.youtube.com/watch?v=MtStd0aeyQA)
- Complex Svelte todo list & others - [YouTube](https://www.youtube.com/watch?v=-XW8xwSk-zU)
- Meteor university in 3.0:
- part 1 - [YouTube](https://www.youtube.com/watch?v=WbwHv-aoGlU)
- part 2 - [YouTube](https://www.youtube.com/watch?v=PB2M16fmloM)
- part 3 - [YouTube](https://www.youtube.com/watch?v=79ytCgZQfSU)
- part 4 - [YouTube](https://www.youtube.com/watch?v=InNCy0duKak)
- TicTacToe & others: [YouTube](https://www.youtube.com/watch?v=MtStd0aeyQA)
- Complex Svelte todo list & others: [YouTube](https://www.youtube.com/watch?v=-XW8xwSk-zU)
- Meteor University with v3
- part 1: [YouTube](https://www.youtube.com/watch?v=WbwHv-aoGlU)
- part 2: [YouTube](https://www.youtube.com/watch?v=PB2M16fmloM)
- part 3: [YouTube](https://www.youtube.com/watch?v=79ytCgZQfSU)
- part 4: [YouTube](https://www.youtube.com/watch?v=InNCy0duKak)
---
If you have a migration guide, it can be video or text, please let us know so we can add it here.
If you have a migration guide, either in video or text format, please share it with us to include here.