rspeedy-bundle-size

Rspeedy バンドル最適化

rspeedy/Lynx アプリのバンドルを削減するための、計測を最優先するワークフローです。中心となる原則は、バイト数がどこにあるかを推測せず、計測し、最も効果の大きい部分から先に攻めることです。「バンドルを最適化する」という要求の多くは、実際の重量がメディアアセットやメインスレッドのリークにあるのに、細かなツリーシェイキングから始めてしまうために失敗します。

ソースを確認する — 推測しない

rspeedy / ReactLynx のビルドは直感に反する挙動をすることがあり、推測すると自信満々に間違えることになります。ビルド、レイヤー、ES ターゲット、あるいは stats/rsdoctor の出力が実際にどう振る舞うか確信が持てないときは、ソースを読んでください — 名前や記憶から推測してはいけません。 ツールチェーン全体はオープンソースです。クローンするか閲覧して、該当するプラグイン/ユーティリティを grep してください:

ツールチェーンのレイヤーは Rspack → Rsbuild → Rspeedy という構成です（それぞれが前のものを基盤としています）。そのため、ある挙動がどのレイヤーに存在するかはさまざまです — 下までたどってください:

• rspeedy + ReactLynx プラグイン（lynx-stack モノレポ）: https://github.com/lynx-family/lynx-stack
• rsbuild（rspeedy が基盤とする Rsbuild レイヤー）: https://github.com/web-infra-dev/rsbuild
• rspack（基盤となるバンドラー。stats/モジュール種別、レイヤー、output.environment）: https://github.com/web-infra-dev/rspack
• rsdoctor: https://github.com/web-infra-dev/rsdoctor

（正確なファイルパスはここでは固定していません — バージョン間で移動するためです。シンボルで検索してください。たとえば ES ターゲットのユーティリティ、stats-json プラグイン、エントリ/レイヤーの設定などです。）このスキルに含まれるいくつかの事実 — main=ES2019 / background=ES2015、layer を持つ stats.json、エントリが 2 レイヤーに分割されること — は、いずれもソースを読むか実際のビルドを実行して確認されたものであり、仮定ではありません。新しい主張にも同じ基準を適用してください。

推測禁止 — 実際のモジュールグラフをたどり、import チェーンを語らないこと

問いが 「なぜ X がバンドルされるのか / 誰が Y を import しているのか / エントリから Z へのチェーンは何か」 である場合、実際のモジュールグラフをたどる必要があり、package.json や直感、あるいは 「依存ツリー経由で入ってきており、./entry.tsx + 4630 modules にスコープホイスティングされている」 のような中途半端な回答からもっともらしいチェーンを描写してはいけません。その + N modules はバンドラーがあなたから辺を隠しているのであって、答えではありません。実際の辺を取得するには:

1. tools.rspack で optimization.moduleIds: 'named' と optimization.concatenateModules: false を設定してビルドします。スコープホイスティング(concatenateModules: true、本番のデフォルト)はimporter の辺を collapse します — ホイストされたすべてのモジュールの importer は連結グループ全体("./entry.tsx + N modules")として報告されるため、誰が何を import しているかを文字通り見ることができません。チェーンをたどるにはこれを無効化することが必須です(サイズが大幅に膨らみます — あるプロジェクトで観測されたのは約 +70%、モジュールグラフによって変動 — なので解析専用です。後で元に戻してください)。De-concat は __split__ も無効化するため、すでにメインスレッドから分割されているコンポーネントが main-thread.js 内で膨らんで再登場します — 「巨大なポップアップ/モーダル」を遅延読み込み候補と呼ぶ前に、実際のビルドとクロスチェックしてください(rspeedy-gotchas.md §11 を参照)。
2. stats.json の reasons[].moduleName から実際の importer の辺を読み取ります(各モジュールはそれを import しているモジュールを列挙しています)。大規模なマルチエントリビルドでは、このファイルは数百 MB から約 1 GB に達することがあり、readFileSync には大きすぎます(ERR_STRING_TOO_LONG)。ストリームで読み取ってください(grep / readline)。(デフォルトの stats プリセットを使ったシングルページビルドははるかに小さくなります — stats: { all: true } か多ページのマージだけがファイルを膨らませます。measure-with-rsdoctor.md を参照してください。)
3. チェーンを 1 ホップずつたどり、各ホップで正確なファイルを報告します。あるホップを実際の reason の辺で裏付けられないなら、そのチェーンは持っていないのです — そう述べ、でっち上げないでください。

このルールが生まれた実際の例: あるアプリの 1388 アイコンの膨張は「app → ビジネスコンポーネントライブラリ → UI ライブラリ → アイコンのバレル」のように見えました — しかしそのアプリはこれらのパッケージをどれも直接 import していませんでした(src/ 内でヒット 0)。de-concat した reasons だけが真の辺を明らかにしました。語られたチェーンはオーナーを誤ったファイルへ導いていたでしょう。実際の reason-edge に裏付けられていない依存チェーンは推測です。推測をチェーンとして提示しないでください。

このスキルを使うべきとき

• 「帮我优化一下包体积」 / 「この rspeedy アプリのバンドルサイズを削減して」
• 「なぜ私のバンドルはこんなに大きいのか」 / 「何がこのバンドルを大きくしているのか」
• ビルド後、ユーザーがサイズの内訳と優先順位付けされた計画を求めている
• ツリーシェイキングがそもそも価値があるかどうか、メディア圧縮やメインスレッドのクリーンアップと比較して判断する

バンドルが過大になる別の原因はマングル失敗です — 本番チャンク内でモジュール接頭辞付きの可読な名前(common_EVENT_NAME、utils_toSomething)が生き残っている状態で、通常は ModuleConcatenation 下での eval() による汚染が原因です。これは references/three-levers.md §Lever 2 の JS レバーの一部として扱われています。

このスキルを使うべきでないとき

これはバンドルサイズ / .lynx.bundle のレバーに限られます — 出荷されるバイトを最適化するものであり、それ以外ではありません。次の場合は別の場所へ:

• ランタイム / レンダリングパフォーマンス(ジャンク、初回描画の遅さ、フレーム落ち) — 別の関心事です。このスキルは実行速度に触れません。
• JS メモリ / ヒープリーク — lynx-js-heap-snapshot-analysis を使ってください。
• ディレクティブのセマンティクス ('background only' の許容形式 / 挙動) — reactlynx-best-practices に従ってください。このスキルはディレクティブをサイズのレバーとして適用するだけです。
• rsdoctor-data.json の深いフォレンジック(モジュール単位の保持セット、重複ツリー) — rsdoctor-analysis を使ってください。このスキルはそれを要約するだけです。
• TS 型 / tsconfig → lynx-typescript。tasm バイナリ形式のデコード → lynx-tasm-codec。

関連スキル

利用可能であれば、これらは隣接する問題についてより深く掘り下げます:

• rsdoctor-analysis — rsdoctor-data.json の詳細な分析 (ツリーシェイキングで保持されたモジュール、重複パッケージ、副作用)。このスキルが要約するだけの重い rsdoctor クエリにはこちらを使用してください。公開: https://github.com/rstackjs/agent-skills/tree/main/skills/rsdoctor-analysis
• reactlynx-best-practices — デュアルスレッドディレクティブに関する権威であり、'background only' / 'background-only' 関数ディレクティブも含みます (その detect-background-only ルールを参照)。ディレクティブのセマンティクスと受け入れられる形式については、ここで再導出するのではなく、こちらに従ってください。
• rushstack-best-practices — Rush モノレポで使用します (rush.json / common/config/rush を検出)。Rush リポジトリでは通常、生の pnpm ではなく rush、rushx、または rush-pnpm を使用すべきです。公開: https://github.com/microsoft/rushstack/blob/main/skills/rushstack-best-practices/SKILL.md

ビルドシステムの把握

計測する前に、リポジトリのビルドオーケストレーターを特定し、pnpm build を前提とするのではなく、そのネイティブなコマンド体系を使用してください:

1. Rush モノレポ — rush.json または common/config/rush/ が存在する場合は、Rush スキルを使用します。プロジェクトのスクリプトはプロジェクトディレクトリから rushx <script> で実行するか、rush build --to . のようなリポジトリスコープのコマンドを実行します。pnpm コマンドが本当に必要な場合にのみ rush-pnpm を使用してください。
2. カスタムラッパーツール — スクリプトや設定が rspeedy を企業/モノレポの CLI の背後にラップしている場合は、rspeedy/pnpm を直接呼び出すよりも、そのドキュメント化されたエントリーポイントを優先してください。
3. 通常の pnpm/npm プロジェクト — リポジトリが Rush 管理ではなく、ラッパーもない場合は、pnpm / npm を直接使用します。

pnpm build を盲目的に実行しないでください。まず package.json、ルートのワークスペースファイル、および既存のプロジェクトドキュメントを読み、その後、リポジトリの環境設定を維持しつつ、対象の rspeedy アプリをビルドする最も限定的なコマンドを選択してください。プロジェクトが Node を固定している場合は、Node バージョンマネージャーを介してそのバージョンを使用してください (例: fnm exec --using=<version> -- ... または nvm exec <version> ...)。

プロジェクトが多い場合はまずトリアージを行いましょう（いきなり全部を構築しない）

以下のプロジェクト単位のワークフローは、まず計測するという方針です。しかし、多数のプロジェクト（「うちの Lynx バンドルを最適化してほしい」、50 以上のアプリのダッシュボードなど）を任された場合、どこを見るべきかを決めるためにすべてをビルドすることはできません。安価なソースレベルのトリアージを実行して、どのプロジェクト／レバーが実際にビルドする価値があるかをランク付けし、その後で選ばれたものに対してまず計測するワークフローを適用します。トリアージでのヒットは「ここを計測する」という意味であり、「肥大化が確認された」という意味ではありません。

スキャナー references/assets/scan-levers.mjs は各プロジェクトのソースを走査し（ビルドなし）、ガードされていないバックグラウンド専用リーク、sideEffects の欠落、インライン／大容量メディア、依存関係の重複によってランク付けします：

node references/assets/scan-levers.mjs --glob <reposRoot>        # rank a fleet
node references/assets/scan-levers.mjs <projectDir> --json out.json

その解釈方法と落とし穴については references/cross-project-triage.md をお読みください（重複依存のカウントは開発ツールチェーンに支配されており、ほとんどがノイズです。ソース上の存在 ≠ メインスレッド上の存在です。テレメトリのシグネチャはプロパティ名を過大にカウントします）。実際の約 370 プロジェクトの集合に対して経験的に言えるのは、約 74% がソースにバックグラウンド専用リークのシグナルを持ち、約 62% がほとんどガードされておらず、約 99% が sideEffects を欠落させているということです。テレメトリと jsb／ネイティブのグルーコードはほぼどこからでも参照されており、そしてほぼ常にガードされていません。

テレメトリ／ロギングは、jsb ベースである場合にのみバックグラウンド専用になります。console ベースのロガー（console.*）はメインスレッドでも動作するため、テレメトリ呼び出しを除去可能として扱う前に、その基盤となる実装を確認してください。jsb ベースである場合、それは広く関連するレバー 3 のシグナルですが、実行する前に計測してください。ブラインド除去（plugin-strip-mt-telemetry.ts + loader、メソッドリストはカスタマイズ可能）は、実際のプロジェクトでわずか −3.9 kB（−0.08%） しか削減できませんでした。これはロガーのインポートが生き残ったためです（最終参照のルール）。したがって、これは計測を助ける手段であり、修正そのものではありません（three-levers.md の §レバー 3 を参照）。「これを入れれば勝てる」というレバーではありません。対照的に、1 行の設定 — extractStr: true — は、6 プロジェクトの集合のラウンドで −1.88% から −5.99% を削減しました（64 ページの文字列の多いアプリでは最大 −1.29 MB、薄いデモや重複した文字列コンテンツが少ないアプリではほぼ 0）。つまり、まだ extractStr を使っていない文字列の多いアプリでは、単にそれを有効にするのが最も投資対効果の高い最初の一手であり、手作業でテレメトリリークを追うよりもはるかに優れています。（ただ extractStr: true を設定するだけにしてください。strLength のしきい値の調整は一般的には推奨されません。）

メンタルモデル：3つのレイヤー、3つのレバー

Lynx アプリのバンドルは2つのスレッドと、非 JS アセットに分かれます。サイズは3か所に存在し、最適化の手法はそれぞれで異なります — これらを混同することが最もよくある間違いです。

レバー	正体	典型的なサイズ	誰が修正できるか
メディアアセット	インライン化または同梱される画像／フォント	多くの場合、単一で最大の塊（数 MB）	アプリコード — 通常は最も ROI が高い
JS — バックグラウンドスレッド	react:background レイヤー、アプリロジック	さまざま	アプリコード — ツリーシェイキング、重複排除
JS — メインスレッド	react:main-thread レイヤー、初回画面描画パス	小さくあるべき；リークが発生する	トレース → モジュール分割（マーカー ≈ 0）；大きなチェーンはライブラリへの要望

それぞれのサイズ測定と対処方法については references/three-levers.md を参照してください。

JS レイヤーが2つある理由をまだご存じない場合は、最適化の前に references/dual-thread-architecture.md をお読みください — 完全なモデルと、すべてのレバー3の修正が依存する 代码裁剪 マクロ表が記載されています。要するに：メインスレッドは初回画面の直接描画を行い、スリムに保つ必要があります；バックグラウンドスレッドはロジック／ライフサイクル／状態を担います。ビルドは main-thread.js + background.js を出力し、エンジンが配布するバイナリ .lynx.bundle にコンパイルされます。ReactLynx は useEffect／componentDidMount／bindtap コールバックを main-thread.js から自動的にシェイクアウトします；判断できない場合は、'background only' または __BACKGROUND__／__MAIN_THREAD__ マクロで誘導します — このメカニズムこそがメインスレッドリークのレバーです。

コアワークフロー

ステップ1 — 測定する（決して省略しない）

何かを提案する前に、モジュールごとの実際の内訳を取得してください。これはユーザーがすでに大まかなサイズ（例：「画像〜10MB、JS〜4MB」）を渡してきたり、特定の変更をただ実行するよう依頼してきた場合でも当てはまります — 出力サイズをちらっと見るのは出発点の仮説であり、モジュールごとの測定ではありません。常に rsdoctor（または stats.json）で内訳を確認し、どのレバーに取り組むか（あるいは実装するか）を決める前に、優先順位付けされた推奨事項を最初に示してください — ユーザーが明示的に要求した変更であっても同様です。要求された変更が間違った（ROI の低い）レバーである場合は、まずそう伝えてください；測定された内訳がそれだけの価値があると確認した後にのみ、それを進めてください。

rspeedy の公式な方法は設定による rsdoctor です — @rsdoctor/rspack-plugin を手動でインストールしないでください、また内部フォークをリバースエンジニアリングしないでください。lynx.config.ts に追加します：

tools: {
  rsdoctor: {
    disableClientServer: true,
    brief: { writeDataJson: true },
  },
}

次に RSDOCTOR=true でビルドします。詳細、許可される設定フィールド、シャーディングされたデータの再構築テクニックについては references/measure-with-rsdoctor.md を参照してください。

前のセクションのビルドシステム対応コマンドを使用します：

# Rush project script
RSDOCTOR=true rushx build

# Wrapper-tooling project (example; prefer the repo's documented command)
RSDOCTOR=true <wrapper> build

# Plain package script
RSDOCTOR=true pnpm build

素早く最初の確認をするためのより軽量な代替手段は、rspeedy 組み込みの stats.json です — 設定で performance.profile: true を有効にするか、単に DEBUG=rspeedy でビルドします（output/stats.json を書き出します）。これはモジュールごとに layer フィールド（react:main-thread／react:background、デモで検証済み）を確かに含むため、2つのスレッドを分離できます。モジュールごとの gzip サイズと重複／ツリーシェイキング分析を無償で得たい場合は rsdoctor を優先してください；追加設定なしでレイヤー対サイズの分割を素早く得たい場合は stats.json を使ってください。詳細は references/measure-with-rsdoctor.md にあります。

ステップ2 — 重量を3つのレイヤーに分類する

rsdoctor の moduleGraph から、module.size.parsedSize（および gzipSize）を次のようにグループ化します：

1. メディア／アセット — 非 JS モジュール、またはアセットモジュール
2. JS react:background — module.layer に background を含む
3. JS react:main-thread — module.layer に main-thread を含む

3つの合計を最初に報告してください。その数値だけでも通常はエンゲージメント全体を決定します — 例えば「14MB のうち 10MB が画像；JS のツリーシェイキングでは約 50KB しか稼げないので、メディアから始めましょう」。

ステップ 3 — ROI でレバーを選び、順番に攻略する

デフォルトの優先順位（数値が別のことを示している場合は上書きしてください）:

1. Media assets        → biggest, easiest wins (compress, dedup, format)
2. JS background       → tree-shaking, duplicate packages, deep imports
3. Main-thread leak    → background-only code that leaked into render path
4. Compile-layer knobs → extractStr, CSS minify, debug-info, lazy bundle — often beats the JS tail

各レバーの具体的なテクニックと判断ポイントについては、references/three-levers.md（レバー 1～4）を参照してください。

ステップ 4 — いつ止めるべきかを知る

十分に最適化されたプロジェクトはいずれ壁にぶつかります。ツリーシェイキングは事実上やり尽くされており（sideEffects が正しく設定されている — あるいは、fleet プロジェクトの約 99% がこのフラグを省略しているため、ミニファイアがすでに同等の DCE を実行済みです）、コードレベルの DCE はバンドルレベルではほぼ 0 の効果しかなく、残るメインスレッドのリークは編集できない SDK ライブラリの内部に存在します。そのことを率直に伝えてください。 忙しく見せるために些細な変更をでっち上げないでください — 壁と、それを動かすために必要なもの（ライブラリ側の 'background only' ディレクティブ、CI におけるアセットパイプラインの変更など）を報告してください。

構造的重複の壁（大規模ページで最もよく見られる形 — 実際の大規模アプリ 2 つを深掘りして検証済み）。 大きな .lynx.bundle は、通常、リークやデッドコードではなく、ファーストスクリーンの直接レンダリングが本当に必要とする重量級リソースが両方のレイヤーに搭載されていること（デュアルスレッドモデルでは、メインスレッドとバックグラウンドがそれぞれ独自のコピーをバンドルします）によって支配されています。実際の 2 つの例: あるアプリのページは 87% が i18n ロケール JSON（57 言語すべて、両方のレイヤーに存在）でした。別のアプリは 62% が Pixi ライクなレンダリングエンジン（各レイヤーで約 1.4 MB）で、これがファーストスクリーンを描画していました。これに遭遇したとき、通常のアプリ側のレバーは構造上すべて失敗します。そして、その理由を説明することが成果物です:

• 遅延分割できない — これはファーストスクリーンの直接レンダリングコンテンツです。遅延させると、ファーストスクリーンはレンダリングの途中でチャンクを読み込むことになります（遅くなる / FOUC が発生する）。（これは遅延バンドルのルールを適用したものです: ファーストスクリーンが必要とするものを決して遅延させない。）
• Strip/DCE/dedup は適用されない — これはデッドコードでも重複したパッケージでもありません。同じ必要なリソースが 2 つのスレッドに正当に存在しているだけです。
• extractStr は文字列型のケースにしか効かない — これは 2 つのレイヤー間で重複した文字列リテラル（i18n ロケールテキスト、クラス名 — だからこそ文字列の多いアプリはこれで大幅に縮小します）を dedup しますが、重複したコード（レンダリングエンジン）は dedup しないため、エンジンのケースには効きません。

したがって、これらの本当のレバーはライブラリ/フレームワークレベルにあり、アプリ側ではありません: より軽量なライブラリ、2 つのスレッド間でコードを共有するフレームワーク機能、あるいはリソース（例: アクティブなロケール）を同期的に注入してバンドルがそれを保持しなくて済むようにするホストです。支配的なチャンクを測定し、それを名指しし、これらのどれが必要かを伝えてください — 重さが構造的なページのためにアプリ側の設定を延々といじらないでください。

rspeedy/Lynx に固有の落とし穴

これを一般的な webpack プロジェクトのように扱うと、いくつかの事柄に引っかかります。設定を編集したり所見を主張したりする前に、references/rspeedy-gotchas.md を読んでください。主な罠は次のとおりです:

• 2 つのスレッドは固定の ES ターゲットで出荷されます — メインスレッド = ES2019、バックグラウンド = ES2015（本番）。どちらもパース速度のために let/const→var に下げます。これらはエンジン駆動のプラットフォーム定数です。バイト数を節約するためにターゲットを変更することを提案しないでください。（一部のプロジェクトではパース時間のために output.environment をさらに低く、完全な ES5 に固定しています — これは意図的なトレードオフであり、標準ではありません。）
• rsdoctor のデータはシャーディングされている可能性があります（単一の JSON ではなく .rsdoctor/ ディレクトリ）— 正しく再構築しないと、数値が間違ってしまいます。
• ビルドには固定された Node が必要です（fnm/nvm 経由、例: fnm exec --using=20.19.0 または nvm exec 20.19.0）— 新しい Node では rspeedy の設定読み込みが壊れる可能性があります。

ログ記録のルール — 最適化ごとに .bundle-opt-log/ エントリーを作成する

あらゆる最適化（分析のみ、実施済みを問わず）で必須です。 最適化対象プロジェクトのルートにある隠しディレクトリ .bundle-opt-log/ の下にログエントリーを作成してください（例：apps/<app>/.bundle-opt-log/）。ログの主指標は、ページごとの .lynx.bundle サイズの最適化前 → 最適化後（配布されるバイナリ）です。

各エントリー（1 ラウンドにつき Markdown ファイル 1 つ。例：2026-06-04-icon-treeshake.md のように日付と施策名をファイル名にする）には、以下を記録します。

• プロジェクト／ページ、最適化前と最適化後の .lynx.bundle サイズ（kB）、および 差分と変化率
• 実施した 施策（1 行）と、ステータス（実施済み／提案／限界）
• 検証用ビルドコマンド（数値を再現可能にするため）と、バージョンが固定されている場合は Node のバージョン
• 該当する場合は 測定上の注意点（例：ウォームキャッシュとコールドキャッシュの違い — Gotchas §7 を参照。差分が約 3% 未満の場合は、ウォーム状態で再測定が必要です）

また、集約トラッキングテーブルを 1 つ維持します（例：.bundle-opt-log/优化记录表.md / SUMMARY.md）。最適化ごとに 1 行を記載した単一の Markdown テーブル（优化项 | .lynx.bundle 前 | 后 | Δ | 机制 | commit）に加えて、累計の合計行と、調査したもののリリースしなかった施策の 2 つ目のテーブル（測定した差分、多くの場合は約 0、およびその理由を記載）を用意してください。最適化を取り込むたびに 1 行追加し、各行の「最適化前」を前の行の「最適化後」とつなげてください。これは一目で確認できる台帳であり、各ラウンドの詳細は個別ファイルに記載します。担当者から特に要望されているテーブルなので、常に最新の状態を保ってください。

.lynx.bundle を中心に記録してください。中間生成物の main-thread.js／background.js の数値は補足情報ですが、主要な数値は常に配布される .lynx.bundle の最適化前後のサイズです。ビルドの 成果物（中間生成物や解析用の連結解除ダンプ）は、Git の追跡対象外であるビルド出力ディレクトリ（output/ または dist/）に保存し、新しい最上位ディレクトリには絶対に置かないでください。リポジトリ内に置くのは .bundle-opt-log/ の Markdown ファイルだけです。.bundle-opt-log/ を作成する前に、コミット対象にするか Git の追跡対象外にするかを担当者に確認してください。

基本方針：まず報告し、デフォルトでは読み取り専用

ここにある他の分析スキルと同様に、デフォルトではコードを編集せず、優先順位を付けたレポートを作成します。調査結果、選択肢、トレードオフを提示し、変更内容はユーザーに選んでもらいます。明示的に依頼された場合に限りアプリのコードを変更し、変更は必要最小限にとどめてください。

回答形式

1. 測定した内訳 — 3 層の合計（メディア／bg JS／main JS）と、各層の最大モジュール
2. 最大の施策 — どの層が支配的か、その理由
3. 優先順位付きのアクション — アクション → 推定削減量 → 工数 → 実施担当（アプリ／ライブラリ／CI）のテーブル
4. メインスレッドへの漏れの追跡 — 漏れがある場合は、疑わしいモジュールと、その上流のインポーター経路／担当者を記載してください。漏れた API 文字列だけを報告しないでください
5. コンパイル層ですぐにできる改善 — 試した、または提案した extractStr／CSS の圧縮／デバッグ情報／lazy-bundle の設定（施策 4）
6. 限界 — すでに最適化されている点と、さらに進めるために必要な外部変更
7. ログエントリー — .bundle-opt-log/ エントリーを作成し、トラッキングテーブルに行を追加します（「ログ記録のルール」を参照）