Peer DependenciesとTree Shaking

Peer依存関係は、ライブラリが必要とするものの、利用者側で提供されることを想定するパッケージを宣言します。ライブラリのpackage.jsonでは、Reactは<回strong>peerDependenciesではなくdependenciesに入れるのではありません。ユーザーがライブラリをインストールしても、npm/yarnはReactを自動的にインストールしません。ユーザーのアプリにはすでにReactがあり、ライブラリはそのインスタンスを共有するためです。

Reactをライブラリのdependenciesに入れると、npmが利用者側のReactとは別に、Reactのコピーをもう1つインストールする場合があります。同じアプリ内にReactのインスタンスが2つあると、すべてのフックが「Invalid hook call」エラーで壊れます。ReactをpeerDependencyとして宣言することで、「Reactは必要ですが、利用者がすでに持っているものを使用してください」とnpmに伝えられます。

peer依存関係の中にはオプションにできるものもあります。たとえば、styled-componentsとCSS Modulesの両方をサポートするライブラリです。peerDependenciesMetaを使ってオプションのpeer依存関係を指定します：{ 'styled-components': { optional: true } }。npmはオプションのpeer依存関係がない場合でもユーザーに警告しませんが、オプションのパッケージがインストールされていれば、TypeScriptの型を提供できます。

package.jsonのsideEffectsフィールドは、ライブラリが安全にツリーシェイキングできるかどうかをバンドラーに伝えます。"sideEffects": falseを設定すると、webpack、Rollupなどのツールに対して、ライブラリからどのモジュールをインポートしても副作用が発生しないことを伝えられます。その結果、使用されていないエクスポートをすべて利用者のバンドルから安全に削除できます。

CSSのインポートは、よくある副作用の1つです。インポートされると、その副作用としてページにスタイルが挿入されるためです。ライブラリがCSSファイルをインポートする場合は、"sideEffects": ["*.css", "*.scss"]を設定してください。これにより、バンドラーに対して、JSファイルは安全にツリーシェイキングできる一方、CSSファイルはインポート時に必ず含める必要があることを伝えられます。

ツリーシェイキングの効果を最大限に高めるには、各コンポーネントを専用ファイルから名前付きエクスポートとして公開します。index.tsですべてを再エクスポートします：export { Button } from './Button'。利用者がButtonだけをインポートした場合、バンドラーはほかのすべてのコンポーネントを削除できます。再エクスポートをまとめるBarrelファイルによって、このパターンを実現できます。

bundlejs.comを使ってツリーシェイキングをテストできます。インポート文を貼り付けると、実際のバンドルサイズが報告されます。size-limit npmパッケージを使うと、package.jsonでサイズ上限を定義し、インポートサイズが上限を超えた場合にCIを失敗させられます："size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }]。

ライブラリのインポートに対するサイズ上限を設定してください。CIでnpx size-limitを実行して、その上限を適用します。バンドルの影響が時間とともに大きくなっている場合は、スコープが肥大化している兆候です。焦点を絞ったコンポーネントライブラリでは、個々のコンポーネントのインポートサイズを数KB以内に抑えるべきです。利用者に影響が及ぶ前に、リグレッションを検出できるようにしてください。

配布を目的とするコンポーネントライブラリでは、styled-componentsとEmotionの使用を避けてください。これらのランタイムCSS-in-JSソリューションでは、利用者にも同じライブラリとバージョンをインストールしてもらう必要があり、peer依存関係の競合が発生します。利用者がTailwindや通常のCSSを使っている場合でも、CSS-in-JSのランタイムをバンドルしなければなりません。ビルド時に通常のCSSへコンパイルされるCSS Modulesを優先してください。

CSS Modulesは、CSSを処理できるバンドラーと組み合わせると、ライブラリでも適切に機能します。tsupとRollupは、CSS Modulesの出力をスコープ付きクラス名としてインライン化できます。利用者側で設定を行う必要はありません。スタイルはすでにスコープ化され、JSバンドルに含まれるか、インポートされる個別のCSSファイルとして提供されるためです。

開発用ツール（tsup、TypeScript、テストライブラリ、Storybook）はdevDependenciesに入れます。これらは開発時にのみ必要で、利用者がnpm installを実行した際にはインストールされません。Reactは、実行時の要件としてpeerDependenciesに、ライブラリをローカルでコンパイルおよびテストするためにdevDependenciesにも入れます。

ライブラリのpackage.jsonで"sideEffects": falseを設定すると、バンドラーには何が伝わりますか？

利用者がアプリのReactインスタンスを共有できるよう、ReactはdependenciesではなくpeerDependenciesに宣言します。sideEffects: falseによって、ライブラリ全体のツリーシェイキングが可能になります。CSSインポートが削除されないよう、sideEffects: ['*.css']を使用します。各ファイルから名前付きエクスポートを行うと、ツリーシェイキングの粒度を最大限に高められます。CIでsize-limitを使ってサイズ上限を適用します。peer依存関係の競合を避けるため、ライブラリではCSS-in-JSよりCSS Modulesを優先してください。