docs(rolldown): add further insights (#1913)

Author: jay-es

guide/rolldown.md

@@ -10,14 +10,16 @@ Rolldown は以下の 3 つの重要な原則に焦点を当てています:
 
 - **スピード**: 最大限のパフォーマンスを実現するために Rust で構築
 - **互換性**: 既存の Rollup プラグインと連携可能
-- **開発者体験**: Rollup ユーザーにとって馴染みのある API
+- **最適化**: esbuild や Rollup が実装しているものを超えた機能を提供
 
 ## Vite が Rolldown に移行する理由
 
 1. **統一化**: Vite は現在、依存関係の事前バンドルには esbuild を、プロダクション環境のビルドには Rollup を使用しています。Rolldown はこれらを単一の高性能バンドラーに統一し、両方の目的に使用できるようにすることで、複雑さを軽減することを目指しています。
 
 2. **パフォーマンス**: Rolldown の Rust ベースの実装は、JavaScript ベースのバンドラーと比較して大幅なパフォーマンスの向上を提供します。具体的なベンチマークはプロジェクトのサイズや複雑さによって異なりますが、初期のテストでは Rollup と比較して有望な速度向上が示されています。
 
+3. **追加機能**: Rolldown は、高度なチャンク分割制御、ビルトインの HMR、モジュールフェデレーションなど、Rollup や esbuild では利用できない機能が導入されています。
+
 Rolldown の背景にある動機についての詳細は、[Rolldown が構築される理由](https://rolldown.rs/guide/#why-rolldown)を参照してください。
 
 ## `rolldown-vite` を試す利点
@@ -74,11 +76,27 @@ Rolldown を搭載した Vite のバージョンは現在、`rolldown-vite` と
 
 Rolldown は Rollup の代替として機能することを目指していますが、まだ実装中の機能や意図的な動作の違いがあります。包括的なリストについては、定期的に更新される[この GitHub PR](https://github.com/vitejs/rolldown-vite/pull/84#issue-2903144667) を参照してください。
 
+### オプション検証エラー {#option-validation-errors}
+
+Rolldown は不明または無効なオプションが渡されるとエラーをスローします。Rollup で利用可能な一部のオプションは Rolldown ではサポートされていないため、使用しているメタフレームワークや自身が設定したオプションに応じてエラーが発生する可能性があります。以下に、このようなエラーメッセージの例を示します:
+
+> Error: Failed validate input options.
+>
+> - For the "preserveEntrySignatures". Invalid key: Expected never but received "preserveEntrySignatures".
+
+このオプションを自身で設定していない場合は、使用しているフレームワークで修正される可能性があります。それまでの間、`ROLLDOWN_OPTIONS_VALIDATION=loose` 環境変数を設定することでこのエラーを抑制できます。
+
+## ネイティブプラグインの有効化
+
+Rolldown と Oxc のおかげで、エイリアスや resolve プラグインなどの Vite の内部プラグインが Rust に変換されました。執筆時点では、これらのプラグインの動作が JavaScript 版とは異なる可能性があるため、デフォルトでは有効になっていません。
+
+これらをテストするには、Vite の設定で `experimental.enableNativePlugin` オプションを `true` に設定できます。
+
 ## 問題の報告
 
 これは実験的な統合であるため、問題が発生する可能性があります。問題が発生した場合は、**メインの Vite リポジトリーではなく**、[`vitejs/rolldown-vite`](https://github.com/vitejs/rolldown-vite) リポジトリーに報告してください。
 
-[問題を報告する](https://github.com/vitejs/rolldown-vite/issues/new)際は、issue テンプレートに従って以下の情報を提供してください:
+[問題を報告する](https://github.com/vitejs/rolldown-vite/issues/new)際は、適切な issue テンプレートに従ってそこで要求されている内容を提供してください。一般的には次のような内容が含まれます:
 
 - 問題の最小限の再現方法
 - 環境の詳細（OS、Node バージョン、パッケージマネージャー）
@@ -92,9 +110,34 @@ Rolldown は Rollup の代替として機能することを目指しています
 
 `rolldown-vite` を試して、フィードバックや問題報告を通じてその開発に貢献することをお勧めします。
 
+将来的には、プロダクションモードだけでなく開発モードでもバンドルされたファイルを提供する「フルバンドルモード」も導入する予定です。
+
+### なぜフルバンドルモードを導入するのか？
+
+Vite は、バンドルしない開発サーバーアプローチを採用しており、これは Vite が最初に導入されたときから高速性と人気の主な理由でした。このアプローチは、従来のバンドル方式を採用せずに開発サーバーのパフォーマンスをどこまで向上できるかを試す実験でした。
+
+しかし、プロジェクトの規模と複雑さが増すにつれ、2 つの主な課題が浮上してきました:
+
+1. **開発/本番環境の不整合**: 開発時にはバンドルされていない JavaScript を提供し、本番環境ではバンドルされたファイルを提供するという違いは、異なるランタイムの挙動を生み出します。これにより本番環境でのみ発生する問題のデバッグが困難になります。
+
+2. **開発時のパフォーマンス低下**: バンドルしないアプローチでは各モジュールが個別にフェッチされるため、大量のネットワークリクエストが発生します。これは本番環境では影響がありませんが、開発サーバーの起動時やページのリフレッシュ時に大きなオーバーヘッドを引き起こします。この影響は、数百から数千のリクエストを処理する必要がある大規模なアプリケーションで特に顕著です。これらのボトルネックは、開発者がネットワークプロキシを使用する場合にさらに深刻になり、リフレッシュ時間が遅くなり開発者体験が低下します。
+
+Rolldown の統合により、Vite の特徴的なパフォーマンスを維持しながら、開発と本番の体験を統一する機会が生まれます。フルバンドルモードでは、開発時にもバンドルされたファイルを提供することで、以下のような利点が得られます:
+
+- 大規模なアプリケーションでも高速な起動時間
+- 開発環境と本番環境での一貫した挙動
+- ページリフレッシュ時のネットワークオーバーヘッドの削減
+- ESM 出力によるの効率的な HMR の維持
+
+フルバンドルモードが導入された際は、まずはオプトイン機能として提供されます。Rolldown の統合と同様に、フィードバックを集めて安定性を確認した後、デフォルトにすることを目指しています。
+
 ## プラグイン / フレームワーク作者向けガイド
 
-### 主な変更点
+::: tip
+このセクションは主にプラグインやフレームワークの作者向けです。ユーザーの方はこのセクションをスキップしてください。
+:::
+
+### 主な変更点の概要
 
 - ビルドに Rolldown が使用されます（以前は Rollup が使用されていました）
 - オプティマイザーに Rolldown が使用されます（以前は esbuild が使用されていました）
@@ -104,11 +147,15 @@ Rolldown は Rollup の代替として機能することを目指しています
 - JS の圧縮にはデフォルトで Oxc minifier が使用されます（以前は esbuild が使用されていました）
 - 設定のバンドルに Rolldown が使用されます（以前は esbuild が使用されていました）
 
-### rolldown-vite の検出方法
+### `rolldown-vite` の検出方法 {#detecting-rolldown-vite}
 
-以下のいずれかの方法で検出できます:
+::: warning
+ほとんどの場合、プラグインが `rolldown-vite` で実行されるか `vite` で実行されるかを検出する必要はなく、条件分岐なしで両方で一貫した動作を目指す必要があります。
+:::
+
+`rolldown-vite` で異なる動作が必要な場合は、`rolldown-vite` が使用されているかどうかを検出する方法が 2 つあります:
 
-- `this.meta.rolldownVersion` の存在を確認する
+`this.meta.rolldownVersion` の存在を確認する:
 
 ```js
 const plugin = {
@@ -122,7 +169,9 @@ const plugin = {
 }
 ```
 
-- `rolldownversion` エクスポートの存在を確認します
+<br>
+
+`rolldownversion` エクスポートの存在を確認する:
 
 ```js
 import * as vite from 'vite'
@@ -138,15 +187,12 @@ if (vite.rolldownVersion) {
 
 ### Rolldown のオプション検証を無視するには
 
-Rolldown は、不明または無効なオプションが渡されるとエラーをスローします。Rollup で利用可能ないくつかのオプションは Rolldown でサポートされていないため、エラーに遭遇する可能性があります。以下に、このようなエラーメッセージの例を見つけることができます:
-
-> Error: Failed validate input options.
->
-> - For the "preserveEntrySignatures". Invalid key: Expected never but received "preserveEntrySignatures".
+[上記で述べたように](#option-validation-errors)、Rolldown は不明または無効なオプションが渡されるとエラーをスローします。
 
-これは、上記のように `rolldown-vite` で実行されているかどうかを確認することでオプションを条件的に渡すことで修正できます。
+これは[上記のように](#detecting-rolldown-vite)、`rolldown-vite` で実行されているかどうかを確認することでオプションを条件的に渡すことで修正できます。
 
-今のところこのエラーを抑制したい場合は、 `rolldown_options_validation = loose` 環境変数を設定できます。ただし、最終的には Rolldown でサポートされていないオプションを渡すのをやめる必要があることに留意してください。
+この場合、`ROLLDOWN_OPTIONS_VALIDATION=loose` 環境変数を設定してエラーを抑制することもできます。
+ただし、**最終的には Rolldown でサポートされていないオプションを渡さないようにする必要がある** ことに注意してください。
 
 ### `transformwithesbuild` は `esbuild` を個別にインストールする必要があります