ライブラリ向けRollupとtsupのバンドル

Vite のデフォルト設定はアプリケーション向けに最適化されています。すべてをバンドルし、アセットを処理して、index.html を生成します。一方、コンポーネントライブラリには異なる出力が必要です。ランタイムオーバーヘッドがなく、React をバンドルせず、適切な TypeScript の型宣言を備えた、純粋な ESM/CJS JavaScript ファイルが求められます。Vite のライブラリモードでも対応できますが、Rollup と tsup の方がこの用途に適しています。

Rollup は長年にわたり、JavaScript ライブラリの標準バンドラーとして使われてきました。クリーンで効率的な出力を生成し、優れた tree-shaking に対応しているほか、ESM と CJS の両方の出力形式をサポートします。Rollup のスコープホイスティングはモジュールラッパーのオーバーヘッドを排除し、ライブラリのバンドルを可能な限り小さくします。

tsup は esbuild を基盤とする、設定不要の TypeScript バンドラーです。esbuild はミリ秒単位でコンパイルする Rollup よりも大幅に高速で、マイクロ秒単位でコンパイルします。最小限の設定である { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } により、両方のモジュール形式と TypeScript の型宣言が自動的に生成されます。

tsup の主なオプションは次のとおりです。entry はエントリーポイントとなるファイルの配列です。format は出力形式を指定し、['esm', 'cjs'] のように記述します。dts: true は JS 出力と同じ場所に .d.ts TypeScript 型宣言ファイルを生成します。target は最小の JavaScript 実行環境（esnext または es2020）を設定します。splitting: false は出力を単一ファイルに保ちます。

esbuild（tsup経由）はRollupより10～100倍高速にコンパイルします。Rollupは、より細かなツリーシェイキングとチャンク境界の制御が可能で、出力もわずかに最適化されます。ほとんどのコンポーネントライブラリでは、開発時の速度という点でtsupが有利です。最大限のツリーシェイキング制御や複雑な複数エントリー構成が必要な場合は、Rollupが適しています。

Reactライブラリで最も重要なバンドラー設定は、ReactやReactDOMを決してバンドルしないことです。ReactとReactDOMを外部として指定し、出力から除外してください。ライブラリがReactをバンドルすると、利用者側ではバンドルに含まれるReactとアプリ側のReactという2つのReactが存在することになります。複数のReactインスタンスが存在すると、すべてのReactフックが機能しなくなります。

tsupの設定では、externalオプションを使用します：external: ['react', 'react-dom']。Rollupの設定では、external: ['react', 'react-dom', 'react/jsx-runtime']を設定します。ライブラリがJSX Transformを使用する場合は、react/jsx-runtimeも含めてください。また、ライブラリが宣言しているほかのpeer依存関係もすべて外部化してください。

TypeScriptライブラリの最小限のRollup設定には、3つのプラグインが必要です。@rollup/plugin-typescriptはTypeScriptのコンパイルに、@rollup/plugin-node-resolveはnode_modulesからのインポート解決に、@rollup/plugin-commonjsはCommonJSの依存関係をバンドル用のESMに変換するために使用します。型宣言ファイルを生成するにはrollup-plugin-dtsを追加してください。

一般的なデュアル形式ライブラリの出力は、ESM利用者向けのdist/esm/index.jsとdist/esm/index.d.ts、CJS利用者向けのdist/cjs/index.jsとdist/cjs/index.cjsです。package.jsonのexportsフィールドによって、これらのパスが適切な環境に割り当てられます。TypeScriptの型宣言ファイルは、対応するJSファイルと同じ場所に配置されます。

大規模なライブラリでは、利用者が必要なものだけをインポートできるよう、複数のエントリーポイントを用意すると効果的です。たとえば、entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']のように設定します。各エントリーには、それぞれ専用の出力ファイルが生成されます。package.jsonのexportsフィールドで、各公開パスを出力先に割り当てます：'./utils' → './dist/utils.js'。

package.jsonのscriptsにビルドコマンドを追加します："build": "tsup"。tsupはルートにあるtsup.config.tsから設定を読み込みます。prepublishスクリプトではビルドを実行してください："prepublishOnly": "npm run build"を設定すると、npmへの公開前に必ずパッケージがビルドされます。

tsup（esbuildベース）は、format: ['esm', 'cjs']とdts: trueによる高速なゼロ設定のバンドリングを提供します。Rollupでは、@rollup/plugin-typescriptによって、より細かなツリーシェイキング制御が可能です。重要なルールは、バンドルへの取り込みを防ぐため、react、react-dom、およびすべてのpeer依存関係を必ず外部として指定することです。dist/esm/とdist/cjs/に出力し、TypeScriptの型宣言も並行して生成します。複数のエントリーポイントにより、利用者側で細かなツリーシェイキングが可能になります。