Meteor 3.0 Migration Guide

Reference document capturing patterns, constraints, and lessons learned during the async migration of WeKan from Meteor 2.16 toward Meteor 3.0 readiness.

1. Dual-Compatibility Strategy

WeKan runs on Meteor 2.16 with Blaze 2.x. The goal is dual compatibility: changes must work on 2.16 now and remain compatible with a future Meteor 3.0 upgrade.

Key constraint: Blaze 2.x does NOT support async template helpers. Client-side code must receive synchronous data.

2. ReactiveCache Facade Pattern

ReactiveCache dispatches to ReactiveCacheServer (async MongoDB) or ReactiveCacheClient (sync Minimongo).

Rule: Facade methods must NOT be async. They return a Promise on the server and data on the client. Server callers await; client code uses the return value directly.

// CORRECT:
getBoard(boardId) {
  if (Meteor.isServer) {
    return ReactiveCacheServer.getBoard(boardId);  // Returns Promise
  } else {
    return ReactiveCacheClient.getBoard(boardId);  // Returns data
  }
}

// WRONG:
async getBoard(boardId) { ... }  // Wraps client return in Promise too!

3. Model Helpers (Collection.helpers)

Model helpers defined via Collection.helpers({}) are used by Blaze templates. They must NOT be async.

// CORRECT:
Cards.helpers({
  board() {
    return ReactiveCache.getBoard(this.boardId);  // Promise on server, data on client
  },
});

// WRONG:
Cards.helpers({
  async board() {  // Blaze gets Promise instead of data
    return await ReactiveCache.getBoard(this.boardId);
  },
});

Server-side callers of these helpers must await the result:

// In a Meteor method or hook (server-only):
const board = await card.board();

4. Allow/Deny Callbacks Must Be Synchronous

Meteor 2.x evaluates allow/deny callbacks synchronously. An async callback returns a Promise:

• allow callback returning Promise (truthy) → always passes
• deny callback returning Promise (truthy) → always denies

Rule: Never use async in allow/deny. Replace ReactiveCache calls with direct sync Mongo calls.

// CORRECT:
Cards.allow({
  insert(userId, doc) {
    return allowIsBoardMemberWithWriteAccess(userId, Boards.findOne(doc.boardId));
  },
  fetch: ['boardId'],
});

// WRONG:
Cards.allow({
  async insert(userId, doc) {
    return allowIsBoardMemberWithWriteAccess(userId, await ReactiveCache.getBoard(doc.boardId));
  },
});

Sync alternatives for common patterns:

Note: These sync Mongo calls (findOne, find().fetch()) are available in Meteor 2.x. In Meteor 3.0, they will be replaced by findOneAsync / find().fetchAsync(), which will require allow/deny callbacks to be reworked again (or replaced by Meteor 3.0's new permission model).

5. Server-Only Code CAN Be Async

Code that runs exclusively on the server can safely use async/await:

• Meteor.methods({}) — method bodies
• Meteor.publish() — publication functions
• JsonRoutes.add() — REST API handlers
• Collection.before.* / Collection.after.* — collection hooks (via matb33:collection-hooks)
• Standalone server functions

Meteor.methods({
  async createCard(data) {
    const board = await ReactiveCache.getBoard(data.boardId);  // OK
    // ...
  },
});

6. forEach with await Anti-Pattern

Array.forEach() does not handle async callbacks — iterations run concurrently without awaiting.

// WRONG:
items.forEach(async (item) => {
  await processItem(item);  // Runs all in parallel, not sequentially
});

// CORRECT:
for (const item of items) {
  await processItem(item);  // Runs sequentially
}

7. Client-Side Collection Updates

Meteor requires client-side collection updates to use _id as the selector:

// CORRECT:
Lists.updateAsync(listId, { $set: { title: newTitle } });

// WRONG - fails with "Untrusted code may only update documents by ID":
Lists.updateAsync({ _id: listId, boardId: boardId }, { $set: { title: newTitle } });

8. Sync Meteor 2.x APIs to Convert for 3.0

These Meteor 2.x sync APIs will need conversion when upgrading to Meteor 3.0:

Current status: Server-side code already uses async patterns via ReactiveCache. The sync findOne() calls in allow/deny callbacks will need to be addressed when Meteor 3.0's allow/deny system supports async (or is replaced).

9. Files Reference

Key files involved in the async migration:

10. FullCalendar Versioning Note (Post-3.0 Follow-Up)

wekan-fullcalendar is currently migrated from legacy Meteor package globals to npm-based FullCalendar 5.11.5 to keep Meteor 2.16 and 3.0 dual compatibility stable.

Why pinned for now:

• Avoids introducing additional breaking changes during core Meteor async migration.
• Keeps compatibility with current Blaze/jQuery-era integration points while removing momentjs:moment Meteor package dependency.

After Meteor 3.0 lands (recommended follow-up):

1. Re-evaluate upgrading FullCalendar to latest stable major.
2. Re-test plugin API differences (especially view names, callback signatures, locale/time formatting, CSS entry points).
3. Verify Node/runtime compatibility and bundle behavior under Meteor 3's final toolchain.
4. Keep migration isolated in a dedicated PR (separate from async data-layer work) to reduce rollback risk.