Dependencias peer y tree shaking

Las peer dependencies declaran los paquetes que su biblioteca necesita, pero que espera que proporcione el consumidor. En el package.json de su biblioteca, React debe estar en peerDependencies, no en dependencies. Cuando un usuario instala su biblioteca, npm/yarn no instala React automáticamente: la aplicación del usuario ya tiene React y su biblioteca comparte esa instancia.

Si React está en las dependencies de su biblioteca, npm podría instalar una segunda copia de React junto a la copia del consumidor. Dos instancias de React en la misma aplicación rompen todos los hooks y provocan el error «Invalid hook call». Al declarar React como peerDependency, le indica a npm: «Necesito React, pero use la instancia que el consumidor ya tiene».

Algunas peer dependencies pueden ser opcionales; por ejemplo, una biblioteca compatible tanto con styled-components como con CSS Modules. Marque las dependencias opcionales mediante peerDependenciesMeta: { 'styled-components': { optional: true } }. npm no advertirá a los usuarios sobre la ausencia de peers opcionales, pero los tipos de TypeScript seguirán disponibles cuando el paquete opcional esté instalado.

El campo sideEffects de package.json indica a los empaquetadores si su biblioteca es segura para aplicar tree-shaking. Establecer "sideEffects": false indica a webpack, Rollup y herramientas similares que importar cualquier módulo de su biblioteca no provoca efectos secundarios; todas las exportaciones no utilizadas pueden eliminarse de forma segura del bundle del consumidor.

Las importaciones de CSS son un efecto secundario habitual: inyectan estilos en la página como consecuencia de su importación. Si su biblioteca importa archivos CSS, establezca "sideEffects": ["*.css", "*.scss"] para indicar a los empaquetadores que los archivos JS se pueden someter a tree-shaking, pero que los archivos CSS deben incluirse siempre cuando se importen.

Para maximizar la eficacia del tree-shaking, exporte cada componente como una exportación con nombre desde su propio archivo. En su index.ts, vuelva a exportar todo: export { Button } from './Button'. Cuando un consumidor solo importa Button, el empaquetador puede eliminar todos los demás componentes. Los archivos barrel con reexportaciones permiten este patrón.

Use bundlejs.com para probar el tree-shaking: pegue su instrucción de importación y se le mostrará el tamaño real del bundle. El paquete npm size-limit le permite definir límites de tamaño en su package.json y hacer que CI falle si el tamaño de la importación supera el límite: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Establezca un presupuesto de tamaño para las importaciones de su biblioteca. Ejecute npx size-limit en CI para hacerlo cumplir. Observar que el impacto del bundle crece con el tiempo indica un aumento descontrolado del alcance. Una biblioteca de componentes enfocada debería mantener las importaciones de cada componente por debajo de unos pocos kilobytes. Genere alertas sobre las regresiones antes de que lleguen a los consumidores.

Evite styled-components y Emotion en las bibliotecas de componentes que pretenda distribuir. Estas soluciones CSS-in-JS en tiempo de ejecución requieren que el consumidor instale la misma biblioteca y versión, lo que crea conflictos entre peer dependencies. Si el consumidor utiliza Tailwind o CSS puro, aun así debe incluir el runtime de CSS-in-JS en su bundle. Prefiera CSS Modules, que se compilan a CSS puro durante la compilación.

CSS Modules funciona bien en bibliotecas cuando se combina con un empaquetador que los procese. tsup y Rollup pueden integrar en línea la salida de CSS Modules como nombres de clase con ámbito. El consumidor no necesita configurar nada: los estilos ya tienen un ámbito definido y se incluyen en el bundle de JS o en un archivo CSS independiente que se importa.

Sus propias herramientas de desarrollo (tsup, TypeScript, bibliotecas de pruebas y Storybook) deben estar en devDependencies: solo se necesitan durante el desarrollo y se excluyen de la instalación de npm para los consumidores. React debe estar tanto en peerDependencies (requisito de ejecución) como en devDependencies (necesario para compilar y probar su biblioteca localmente).

¿Qué comunica a los empaquetadores establecer "sideEffects": false en el package.json de una biblioteca?

Declare React en peerDependencies (no en dependencies) para que los consumidores compartan la instancia de React de su aplicación. sideEffects: false permite aplicar tree-shaking completo a su biblioteca. Use sideEffects: ['*.css'] para proteger las importaciones de CSS frente a la eliminación. Las exportaciones con nombre desde archivos individuales maximizan la granularidad del tree-shaking. Imponga un presupuesto de tamaño con size-limit en CI. Prefiera CSS Modules frente a CSS-in-JS en las bibliotecas para evitar conflictos entre peer dependencies.