Dipendenze peer e tree shaking

Le peer dependencies dichiarano i pacchetti richiesti dalla libreria, che tuttavia si aspetta vengano forniti dal consumer. Nel package.json della libreria, React deve trovarsi in peerDependencies, non in dependencies. Quando un utente installa la libreria, npm/yarn non installa automaticamente React: l'app dell'utente ha già React e la libreria condivide quella stessa istanza.

Se React si trova nelle dependencies della libreria, npm potrebbe installare una seconda copia di React accanto a quella del consumer. Due istanze di React nella stessa app interrompono tutti gli hook e causano l'errore "Invalid hook call". Dichiarando React come peerDependency, comunica a npm: "Mi serve React, ma utilizzi quello che il consumer ha già."

Alcune peer dependencies possono essere opzionali, ad esempio una libreria che supporta sia styled-components sia CSS Modules. Contrassegni le peer opzionali utilizzando peerDependenciesMeta: { 'styled-components': { optional: true } }. npm non mostrerà agli utenti avvisi relativi alle peer opzionali mancanti, ma i tipi TypeScript potranno comunque essere forniti quando il pacchetto opzionale sarà installato.

Il campo sideEffects in package.json indica ai bundler se la libreria può essere sottoposta al tree-shaking in sicurezza. Impostare "sideEffects": false comunica a webpack, Rollup e strumenti simili che l'importazione di qualsiasi modulo della libreria non produce effetti collaterali: tutte le esportazioni inutilizzate possono essere rimosse senza rischi dal bundle del consumer.

Gli import CSS sono un effetto collaterale comune: iniettano gli stili nella pagina come effetto dell'importazione. Se la libreria importa file CSS, imposti "sideEffects": ["*.css", "*.scss"] per comunicare ai bundler che i file JS possono essere sottoposti al tree-shaking, mentre i file CSS devono essere sempre inclusi quando vengono importati.

Per ottenere il massimo dal tree-shaking, esporti ogni componente come named export dal proprio file. Nel file index.ts, riesporti tutto: export { Button } from './Button'. Quando un consumer importa solo Button, il bundler può eliminare tutti gli altri componenti. I barrel file con riesportazioni consentono di adottare questo schema.

Utilizzi bundlejs.com per testare il tree-shaking: incolli la sua istruzione di importazione e il servizio riporta le dimensioni effettive del bundle. Il pacchetto npm size-limit consente di definire budget delle dimensioni nel package.json e di interrompere la CI se le dimensioni dell'import superano il limite: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Definisca un budget delle dimensioni per gli import della libreria. Esegua npx size-limit nella CI per farlo rispettare. Un aumento nel tempo dell'impatto del bundle indica un'espansione incontrollata dell'ambito. Una libreria di componenti mirata dovrebbe mantenere gli import dei singoli componenti al di sotto di pochi kilobyte. Rilevi le regressioni prima che raggiungano i consumer.

Eviti styled-components ed Emotion nelle librerie di componenti che intende distribuire. Queste soluzioni CSS-in-JS a runtime richiedono che il consumer installi la stessa libreria e la stessa versione, creando conflitti tra peer dependencies. Se il consumer utilizza Tailwind o CSS semplice, deve comunque includere nel bundle il runtime CSS-in-JS. Preferisca CSS Modules, che vengono compilati in CSS semplice durante la build.

I CSS Modules funzionano bene nelle librerie se combinati con un bundler che li elabora. tsup e Rollup possono incorporare l'output dei CSS Modules utilizzando nomi di classe con scope. Il consumer non deve configurare nulla: gli stili sono già isolati e inclusi nel bundle JS oppure in un file CSS separato che viene importato.

I propri strumenti di sviluppo (tsup, TypeScript, librerie di test, Storybook) vanno inseriti in devDependencies: servono solo durante lo sviluppo e sono esclusi dall'installazione npm per i consumer. React va inserito sia in peerDependencies (requisito a runtime) sia in devDependencies (necessario per compilare e testare localmente la libreria).

Cosa comunica ai bundler l'impostazione "sideEffects": false nel package.json di una libreria?

Dichiari React in peerDependencies (non in dependencies), così i consumer condividono l'istanza di React della propria app. sideEffects: false abilita il tree-shaking completo della libreria. Utilizzi sideEffects: ['*.css'] per proteggere gli import CSS dall'eliminazione. I named export provenienti da singoli file massimizzano la granularità del tree-shaking. Imponga un budget delle dimensioni con size-limit nella CI. Preferisca CSS Modules a CSS-in-JS nelle librerie per evitare conflitti tra peer dependencies.