Meteor 3 Migration Guide Feedback

[zodern]

Meteor.call x Meteor.callAsync

It is recommened to use Meteor.callAsync instead of Meteor.call because of how our async API works. Meteor.call is still available but it is not recommended to use it, it can lead to unexpected behavior.

What is the unexpected behavior? The one's I am aware of are:

• it does not support async method stubs on the client
• it no longer blocks on the server when called without a callback

It might be helpful to specify what the limitations are so apps can decide how important migrating these are.

Rules of using Meteor.callAsync & Meteor.call

This section seems to be outdated. After #12897 there are no restrictions on when methods are called. The only remaining limitation from Meteor 2 is method stubs should not use api's that create macrotasks (it's a little more important in Meteor 3 since this is what allows the other limitations to be removed).

Slightly off topic, but Meteor 3 still links to the docs in https://github.com/zodern/fix-async-stubs. It would be nice if this changed so it is clearer which repository issues should be opened in.

A related section is "Call x CallAsync" in the Breaking Changes, and there's a few other places where the restrictions on calling methods are mentioned.

Frequently Asked Questions

How to update from version 2?

This section recommends running meteor reset. It shouldn't be necessary, and if it is it probably indicates a bug in Meteor 3.

Will MongoDB Collection Methods be removed from the server?

This section says "Yes, we will remove those MongoDB collection methods that do not end with *Async." There are some exceptions to this, for example collection.countDocuments.

It might be good to also document somewhere that there are exceptions where the sync collection methods are still available on the server:

• when using a DDP client on the server and creating collections for that client (though for some reason the ddp client store becomes async on the server, which seems like a bug.)
• when creating an unnamed in-memory collection

Breaking changes

Changes in Webapp
...
Changed engine from connect to express and changed api naming to match express. See below:

It probably should mention that the old names are still available and will work in Meteor 3

Upgrading packages

Changes for packages that do not use Meteor packages that had breaking change

When a package does not use Meteor packages that had breaking changes, then it should work in Meteor 3 with no changes.

The example of mdg:seo doesn't fit in this category since it does use a package that had breaking changes (webapp).

Other

One thing that seems to be missing is a mention that async fiber code (for example, collection.count()) in the top-level of a module can be migrated to use top level await.

It might also be nice to have documentation on how to make a build plugin that works in both Meteor 2 and 3, since some build plugin maintainers are interested in doing this.