migrate-to-rspack

既存のアプリを Rspack に移行する

Rspack はアプリのコードをコンパイルし、Meteor は Atmosphere パッケージをビルドしてバンドルを組み立てます。パッケージは維持しつつ、アーキテクチャとブラウザー依存関係を監査してください。

Meteor 3.4 以降が必要です。まず "meteor": { "modern": true } を有効にして、Babel のフォールバックを修正することをおすすめします。セットアップやヘルパーについては、meteor-modern-build-stack を使用してください。

@meteorjs/rspack のバージョンは、@rspack/core や @rspack/cli ではなく、Meteor のリリースに合わせてください。

Meteor	rspack	@meteorjs/rspack	対応範囲
3.4	1.0.0	1.0.0	基本的な統合とヘルパー。
3.4.1 and 3.5	1.1.0	2.0.1	v2 ヘルパーと継承された TOOL_NODE_FLAGS を追加。
3.5.1	1.2.0	2.1.0	クライアントのポリフィルと拡張機能の検出を改訂。
3.5.2	1.3.0	2.2.0	依存関係の診断、モードの分離、アプリ全体／TLA とキャッシュの修正。
3.6-beta.0	1.4.0-beta360.0	3.0.0-beta.1	Rspack 2.2.0 とワークスペース対応のインストール。
3.6-beta.1	1.4.0-beta360.1	3.0.0-beta.2	TypeScript の再ビルドループを修正。Node 26.8.2。
3.6-beta.3	1.4.0-beta360.3	3.0.0-beta.3	Rspack 2.2.7。アーキテクチャグラフとテスト除外の修正。
3.6-rc.0	1.4.0-rc360.0	3.0.0-rc.0	Rspack 2 とアーキテクチャごとの個別エントリー。

.meteor/versions、package.json、ロックファイルを確認してください。Atmosphere、Meteor の npm 統合、Rspack コアの各バージョンは独立しています。自動インストールが有効な場合、起動時に依存関係が揃えられます。変更内容を確認し、コミットしてください。代わりに meteor update --npm を使用することもできます。リリースの組み合わせは維持してください。

すでに Rspack を使用していますか？Meteor 3.6 のベータ版または RC にアップグレードする場合は、Rspack 1 to 2 とそのツールチェーンの確認手順に従ってください。有効なエントリーや設定は維持し、以下の初回有効化手順はスキップしてください。

判断の流れ

1. アプリの package.json で meteor.mainModule にクライアントとサーバーのエントリーポイントを定義していますか？いいえの場合は定義してください。必須です。
2. クライアントとクライアントテストのグラフをたどってください。CommonJS のエクスポート代入、Node の組み込みモジュール、サーバー専用のローカルパッケージエントリー、またはクリーンなチェックアウトで生成済みの入力ファイルが見つからない箇所に到達しますか？はいの場合は、有効化の前に境界を修正してください。references/client-graph-preflight.md を参照してください。
3. アプリのコードにネストされたインポート（if、関数、その他のブロック内の ES import）が含まれていますか？はいの場合は、トップレベルに移動するか、動的な import()／require に変換してください。アプリのコードでは必須です。Atmosphere パッケージでは問題ありません。
4. アプリが Meteor のビルドプラグイン（less、fourseven:scss、coffeescript、zodern:melte、jorgenvatle:vite）に依存していますか？削除する前に、Rspack ローダーへの置き換えを計画し、機能の同等性を確認してください。references/framework-and-css.md を参照してください。
5. アプリが CommonJS パッケージからのデフォルトの名前のみのインポート（import x from "some-cjs"）に依存していますか？import * as x に書き換えるか、.swcrc で Meteor 形式の相互運用を復元するかを決めてください。references/code-migrations.md を参照してください。
6. アプリはサーバー専用ですか？mainModule.server のみを設定してください。Rspack は引き続きサーバーをバンドルし、クライアントはスキップされます。
7. アプリのエントリーフォルダーの外に CSS や HTML を置いていますか？または、アプリ内のシンボリックリンクをインポートしていますか？meteor.modules または resolve.symlinks: false を使って境界を維持してください。参考資料を参照してください。
8. meteor add rspack を実行し、詳細な [Transpiler] ログに残る (app) の失敗を確認してください。

必須：エントリーポイント

{
  "meteor": {
    "mainModule": {
      "client": "client/main.js",
      "server": "server/main.js"
    },
    "testModule": "tests.js"
  }
}

mainModule がないと、Rspack にエントリーがありません。Meteor の先行読み込みモデルは適用されません。Rspack はモジュールを自動検出しません。CSS と HTML のルーティングについては、references/framework-and-css.md を参照してください。

3.6-beta.3 および RC の個別の legacy／native エントリーと、それ以前のバージョンの制限については、アーキテクチャの維持を参照してください。

必須：アプリのコードにネストされたインポートを含めない

アプリのコードにネストされたインポートの書き換えを適用してください。Promise を返す import() を使用する場合は、呼び出し元も適切に変更してください。Atmosphere パッケージのコードは、引き続き Meteor のバンドラーで処理されます。

必須：ビルドフォルダーを予約する

このインテグレーションは _build/、public/build-assets/、 public/build-chunks/、private/build-assets/ に書き込みます。 これらは .gitignore に自動追加されます。プロジェクトですでにこれらの名前を使用している場合は、package.json で名前を変更してください。

{
  "meteor": {
    "buildContext": "build",
    "assetsContext": "assets",
    "chunksContext": "chunks"
  }
}

これらのフォルダー内のファイルは編集しないでください。IDE のインデックス作成と、 再帰的なフォーマッター、リンター、型チェッカー、テスト検出、カバレッジスキャンのすべてから除外してください。 .gitignore はこれらのツールを設定しません。

.meteorignore または METEOR_IGNORE で、アクティブなビルドコンテキストに一致する指定をしないでください。 Rspack はそこに Meteor 向けのエントリーモジュールを書き込み、その後 Meteor がそれを読み込んで 最終バンドルを組み立てます。無視設定を監査する前に、名前を変更したコンテキストを解決してください。

ビルドプラグインの置き換え

ほとんどのアプリファイル用ビルドプラグインは、Rspack ローダーに移行します。削除する前に機能が同等であることを確認してください。競合する有効化と削除は、取り消し可能な1つの変更として行ってください。 references/framework-and-css.md を参照してください。

旧プラグイン	置き換え
meteor/less	less-loader。references/framework-and-css.md を参照してください。
fourseven:scss	sass-loader + sass-embedded。参考資料を参照してください。スケルトンは meteor create --full にあります。
meteor/coffeescript	coffee-loader（必要に応じて swc-loader と連結）。
zodern:melte (Svelte)	公式の Rspack Svelte ローダー。
jorgenvatle:vite (Vue/Solid)	ネイティブの Rspack Vue/Solid ローダー。
babel-plugin-react-compiler	3.6 ベータ版の組み合わせでは SWC、それ以前のインテグレーションでは Babel を引き続き使用します。フレームワークのリファレンスを参照してください。
zodern:types	バンドラーの移行中は、動作中の宣言プロバイダーを維持してください。beta.1 のネイティブ採用は、別途明示的に選択します。

Atmosphere パッケージのファイルにのみ作用するプラグインは、そのまま使用できます。アプリフォルダー内のファイル（エントリーフォルダーを除く）に作用するプラグインは、Rspack に移行する必要があります。

CommonJS のデフォルトインポートの相互運用性

名前空間インポートを優先してください。相互運用性のオーバーライドと、アプリ全体に及ぶ CommonJS／ツリーシェイキングのコストについては、references/code-migrations.md をお読みください。

CI と Docker

必要な npm の更新をローカルで解決し、package.json とロックファイルをコミットしてください。 既存のパッケージマネージャーで開発依存関係を含む固定インストールを行ってから、ビルドしてください。 [email protected]（Meteor 3.5.2）では、meteor.autoInstallDeps: false を指定しても、 不足または古い依存関係と手動コマンドが報告されます。それ以前のオプトアウト動作では、 これらのチェックがスキップされる場合があります。修正方法を選ぶ前に、最初の依存関係／設定エラーと 実際のプロジェクトルートを確認してください。references/troubleshooting.md を参照してください。

アンチパターン

• Babel のフォールバックを修正する前に Rspack を追加する。"meteor": { "modern": { "transpiler": { "verbose": true } } } を使って フォールバックを見つけ、最適化のみのスタックを使っている間に修正してください。
• 少数のインポートの移行を避けるために、.swcrc で CJS 相互運用性をグローバルに復元する。短期的な利便性と引き換えに、実際のバンドルサイズ削減効果を失います。
• _build/、public/build-assets/、public/build-chunks/、 private/build-assets/ をコミットする。これらは自動生成されます。
• 対応する依存関係を確認せず、正規のロックファイルをコミットせずにリリースを変更する。クリーンインストールと本番ビルドを検証してください。

関連項目

• references/eval-cases.md
• セットアップ、ヘルパー、rspack.config.js API については、meteor-modern-build-stack を参照してください。