migrate-to-meteor-3

Meteor 2.x アプリケーションを Meteor 3.x に移行する

Meteor 3 では Fibers が削除されました。サーバー側の Mongo API は非同期です。モジュールシステムでは厳格モードが強制されます。非同期コード内のクライアントのリアクティビティには注意が必要です。Atmosphere パッケージは、多くの場合フォークまたは置き換えが必要です。移行は段階的に進めてください。最初にフレームワークのバージョンフラグを切り替えないでください。

推奨される戦略

3.6-beta.3 または 3.6-rc.0 に向けて、更新前に以前のリリースで保持されるローカルデータを準備します。

1. プロジェクトを最新の 2.x リリースに更新します。
2. WARN_WHEN_USING_OLD_API=true meteor run でアプリを実行します。コンソールには、対応する非同期版が必要な同期 API 呼び出しがすべて記録され、フレームワークを切り替える前に対応すべき項目の一覧が得られます。
3. 2.x のまま、サーバー側の同期 Mongo 呼び出しを対応する *Async 版に移行します。変更した各関数について、サーバー側の呼び出し元をすべてたどります。呼び出し元が値を使う箇所では await し、Promise は意図的に引き継ぎ、同期専用の境界は再構成します。非同期に対応したフレームワークの境界でのみ処理を止めます。references/async-rewrites.md と references/call-vs-callAsync.md を参照してください。コミュニティ製の jscodeshift コードモッドで簡単なケースは自動化できますが、標準外のコレクションインポート（例：meteor/<publisher>:collections）は見落とされます。差分を手作業で確認し、コールバックにおける Promise の所有権とコレクション引数の形式を監査してください。
4. Atmosphere パッケージを監査します。代替パッケージを探すか、古いパッケージをフォークし、api.versionsFrom(['2.x', '3.0']) を固定します。references/package-triage.md を参照してください。パッケージのメジャーバージョン変更と Meteor の変更を区別できるよう、.meteor/versions と npm のロックファイルのチェックポイントを保存します。
5. 選択した Meteor 3.x リリースにアップグレードします。
6. 暗黙のグローバル変数を洗い出し、const または export／import を使うように書き換えます。references/module-system.md を参照してください。
7. await の後にリアクティビティが失われる可能性があるため、Blaze ヘルパーと Tracker.autorun ブロックを監査します。references/client-reactivity.md を参照してください。
8. await を含むイテレーター（forEach、map、filter）を for...of または Promise.all に置き換えます。references/js-iterators.md を参照してください。
9. 内部カーソル API（_cursorDescription、手動の sub.added）を使うパブリケーションと、呼び出し時の this を読み取るフレームワークハンドラーを監査します。同期・非同期いずれの publish ハンドラーもカーソルを返せます。カーソル変換は同期のままにし、Meteor に this をバインドさせる場合は通常の関数を使います。パッケージが EnvironmentVariable で Meteor.publish をパッチする場合、publish.call のスコープは呼び出されたハンドラー内ではなく、ラッパーのトップレベルに設定します。await の前後で呼び出しコンテキストを確認してください。references/publications.md と references/other-breaking-changes.md を参照してください。
10. TypeScript プロジェクトでは、対象リリースと既存の型定義プロバイダーを確認します。動作している @types/meteor または zodern:types の構成は維持してください。Meteor 3.6-beta.1 では meteor types による明示的なネイティブオプトインが追加されます。それ以前のリリースでは従来のワークフローが引き続き使われます。references/typescript-migration.md を参照し、その後、プロバイダーの変更と確認には meteor-typescript を使います。
11. React プロジェクトでは、Suspense に対応した react-meteor-data のインポートを採用するか決めます。references/react-migration.md を参照し、その後、最新のフック、スキャフォールド、ビルドに関するガイダンスには meteor-react を使います。

症状別リファレンス

症状	リファレンス
TypeError: Collection.findOne is not a function	references/async-rewrites.md
メソッドが undefined を返す、または Promise を返す	references/async-rewrites.md
下流の呼び出し元が Promise を受け取る、または Promise から値を読み取る	references/async-rewrites.md
Cron、フック、タイマー、イベントのコールバックで Promise が失われる	references/async-rewrites.md
読み取りメソッドに $set、$push、または別の更新演算子が渡される	references/async-rewrites.md
allow / deny バリデーターで非同期データベース読み取りが必要	references/async-rewrites.md
Meteor.call のコールバックが一度も実行されない	references/call-vs-callAsync.md
起動時に ReferenceError: X is not defined が発生	references/module-system.md
テンプレートは描画されるがデータがなく、Minimongo が空	references/module-system.md
Iron Router コントローラーが何も通知せず実行されない	references/module-system.md
Blaze で {{> partial}} が何も描画しない	references/module-system.md
ページは描画されるが、ライブデータが更新されない	references/client-reactivity.md
Blaze ヘルパーが Promise を返す	references/client-reactivity.md
カーソルの transform が「returned a Promise」エラーになる	references/publications.md
sub.added の書き込みがクライアントに届かない	references/publications.md
メソッドまたはパブリケーションで this.userId が失われる	references/publications.md
Atmosphere パッケージの解決またはビルドに失敗する	references/package-triage.md
await を使った forEach/map/filter で項目がスキップされる	references/js-iterators.md
WebApp.connectHandlers のミドルウェアが実行されない	references/webapp-express.md
Meteor 3.1 以降でルートに名前なしワイルドカードを使っている	references/webapp-express.md
rawCollection のコールバックが一度も実行されない	references/other-breaking-changes.md
パッチ適用済みのパブリケーションで Meteor.userId() または非同期コンテキストが失われる	references/other-breaking-changes.md
meteor reset でローカルの Mongo が消去されなかった	references/other-breaking-changes.md
コンソールに「Method stub (X) took too long」という警告が表示される	references/call-vs-callAsync.md
meteor update 中に「Cannot enlarge memory array」が発生する	references/other-breaking-changes.md
外部コールバックで this.userId または環境変数が失われる	references/other-breaking-changes.md
モンキーパッチを適用した Meteor.publish が一度も実行されない	references/other-breaking-changes.md
TypeScript で meteor/* のインポートが any として解決される	references/typescript-migration.md
useTracker または useSubscribe が再実行されない	references/react-migration.md

アンチパターン

• 先に meteor update --release=3 を実行しないでください。まず 2.x で非同期処理への変換とパッケージのトリアージを行ってください。
• findOne を一括で findOneAsync に置き換えないでください。呼び出し元の多くは、単に await を付けるだけでなく、書き換える必要があります。
• クライアントの Minimongo 呼び出しを機械的に非同期処理へ書き換えないでください。クライアントではどちらの API も利用できます。自然に同期処理となる Blaze や Tracker のコードでは同期呼び出しを優先し、共有フローやすでに非同期のフローでは非同期呼び出しを使用してください。await の後でリアクティブな読み取りを行う場合は、Tracker.withComputation で囲んでください。
• Iron Router のコントローラー名の規約による検索に依存しないでください。すべてのルートで controller: を明示的に渡してください。
• 同じ関数内で await と .then() を混在させないでください。どちらか一方を選んでください。
• 暗黙のグローバルが動作すると想定しないでください。3.x では、すべてのトップレベル識別子を const、let、または export で宣言する必要があります。
• 非同期の代替手段を勝手に作らないでください。Meteor.userId() はメソッドやパブリケーション内では引き続き同期処理です。Meteor.userIdAsync() はありません。
• フレームワークによってバインドされた this を読み取るメソッドまたはパブリケーションのハンドラーに、アロー関数を使用しないでください。アロー関数は、Meteor が渡す呼び出しコンテキストを無視します。
• アプリを Meteor 3 に移行したことだけを理由に、api.addFiles や api.export を書き換えないでください。これらは Atmosphere パッケージで引き続きサポートされています。

関連項目

• 非同期処理：async-rewrites.md、call-vs-callAsync.md、async-cheatsheet.md、 js-iterators.md、removed-functions.md。
• ランタイム：module-system.md、client-reactivity.md、publications.md、 webapp-express.md、other-breaking-changes.md。
• プロジェクト：package-triage.md、typescript-migration.md、 react-migration.md、eval-cases.md。
• アップグレード後の現在の Meteor React 統合：meteor-react。

ケーススタディの依頼があった場合は、 references/community-case-studies.md を読み、修正には症状ルーターを使用してください。