Peer Dependencies and Tree Shaking

Peer dependencies declare packages that your library requires but expects the consumer to provide. In your library's package.json, React belongs in peerDependencies, not dependencies. When a user installs your library, npm/yarn does not install React automatically — the user's app already has React, and your library shares that instance.

If React is in your library's dependencies, npm may install a second copy of React alongside the consumer's React. Two React instances in the same app break all hooks with the "Invalid hook call" error. By declaring React as a peerDependency, you tell npm "I need React, but use the one the consumer already has."

Some peers may be optional — for example, a library that supports both styled-components and CSS Modules. Mark optional peers using peerDependenciesMeta: { 'styled-components': { optional: true } }. npm will not warn users about missing optional peers, but TypeScript types can still be provided when the optional package is installed.

The sideEffects field in package.json tells bundlers whether your library is safe to tree-shake. Setting "sideEffects": false tells webpack, Rollup, and similar tools that importing any module from your library does not cause side effects — all unused exports can be safely eliminated from the consumer's bundle.

CSS imports are a common side effect — they inject styles into the page as a side effect of being imported. If your library imports CSS files, set "sideEffects": ["*.css", "*.scss"] to tell bundlers that JS files are safe to tree-shake but CSS files must always be included when imported.

For maximum tree-shakability, export each component as a named export from its own file. In your index.ts, re-export everything: export { Button } from './Button'. When a consumer only imports Button, the bundler can eliminate all other components. Barrel files with re-exports enable this pattern.

Use bundlejs.com to test tree-shaking: paste your import statement and it reports the actual bundle size. The size-limit npm package lets you define size budgets in your package.json and fail CI if the import size exceeds the limit: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Establish a size budget for your library imports. Run npx size-limit in CI to enforce it. Seeing the bundle impact grow over time indicates scope creep. A focused component library should keep individual component imports under a few kilobytes. Alert on regressions before they reach consumers.

Avoid styled-components and Emotion in component libraries you intend to distribute. These runtime CSS-in-JS solutions require the consumer to install the same library and version, creating peer dependency conflicts. If the consumer uses Tailwind or plain CSS, they must still bundle the CSS-in-JS runtime. Prefer CSS Modules, which compile to plain CSS at build time.

CSS Modules work well in libraries when combined with a bundler that processes them. tsup and Rollup can inline CSS Modules output as scoped class names. The consumer does not need to configure anything — the styles are already scoped and included in the JS bundle or as a separate CSS file that gets imported.

Your own development tools (tsup, TypeScript, testing libraries, Storybook) go in devDependencies — they are only needed during development and are excluded from npm install for consumers. React goes in both peerDependencies (runtime requirement) and devDependencies (needed to compile and test your library locally).

What does setting "sideEffects": false in a library's package.json communicate to bundlers?

Declare React in peerDependencies (not dependencies) so consumers share their app's React instance. sideEffects: false enables full tree-shaking of your library. Use sideEffects: ['*.css'] to protect CSS imports from elimination. Named exports from individual files maximize tree-shaking granularity. Enforce a size budget with size-limit in CI. Prefer CSS Modules over CSS-in-JS in libraries to avoid peer dependency conflicts.