Peer dependencies och tree shaking

Peer dependencies deklarerar paket som ert bibliotek kräver men förväntar sig att användaren tillhandahåller. I bibliotekets package.json ska React ligga i peerDependencies, inte i dependencies. När en användare installerar ert bibliotek installerar npm/yarn inte React automatiskt – användarens app har redan React, och ert bibliotek delar den instansen.

Om React ligger i bibliotekets dependencies kan npm installera en andra kopia av React bredvid användarens React. Två React-instanser i samma app gör att alla hooks slutar fungera och ger felet "Invalid hook call". Genom att deklarera React som en peerDependency talar ni om för npm: "Jag behöver React, men använd den som användaren redan har."

Vissa peers kan vara valfria – till exempel i ett bibliotek som stöder både styled-components och CSS Modules. Markera valfria peers med peerDependenciesMeta: { 'styled-components': { optional: true } }. npm varnar då inte användarna om saknade valfria peers, men TypeScript-typer kan fortfarande tillhandahållas när det valfria paketet är installerat.

Fältet sideEffects i package.json talar om för bundlers om ert bibliotek är säkert att tree-shaka. Om ni anger "sideEffects": false talar ni om för webpack, Rollup och liknande verktyg att import av en modul från ert bibliotek inte orsakar sidoeffekter – alla oanvända exporter kan då tas bort säkert från användarens bundle.

CSS-importer är en vanlig sidoeffekt – de lägger till formatmallar på sidan som en sidoeffekt av att importeras. Om ert bibliotek importerar CSS-filer anger ni "sideEffects": ["*.css", "*.scss"] för att tala om för bundlers att JS-filer kan tree-shakas säkert men att CSS-filer alltid måste inkluderas när de importeras.

För maximal möjlighet till tree-shaking exporterar ni varje komponent som en namngiven export från sin egen fil. I index.ts exporterar ni sedan allt igen: export { Button } from './Button'. När en användare bara importerar Button kan bundlern ta bort alla andra komponenter. Barrel-filer med vidareexporter möjliggör detta mönster.

Använd bundlejs.com för att testa tree-shaking: klistra in ert import-uttryck så rapporterar tjänsten den faktiska bundle-storleken. npm-paketet size-limit låter er definiera storleksgränser i package.json och få CI att misslyckas om importstorleken överskrider gränsen: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Fastställ en storleksbudget för importer från ert bibliotek. Kör npx size-limit i CI för att upprätthålla den. Om bundlens påverkan växer över tid tyder det på att bibliotekets omfattning gradvis ökar. Ett fokuserat komponentbibliotek bör hålla importer av enskilda komponenter under några kilobyte. Lägg in varningar för regressioner innan de når användarna.

Undvik styled-components och Emotion i komponentbibliotek som ni tänker distribuera. Dessa CSS-in-JS-lösningar vid körning kräver att användaren installerar samma bibliotek och version, vilket skapar konflikter mellan peer dependencies. Även om användaren använder Tailwind eller vanlig CSS måste CSS-in-JS-körmiljön fortfarande bundlas. Föredra CSS Modules, som kompileras till vanlig CSS vid byggtillfället.

CSS Modules fungerar bra i bibliotek när de kombineras med en bundler som bearbetar dem. tsup och Rollup kan bädda in CSS Modules-utdata som scopade klassnamn. Användaren behöver inte konfigurera något – formaten är redan scopade och inkluderade i JS-bundlen eller i en separat CSS-fil som importeras.

Era egna utvecklingsverktyg (tsup, TypeScript, testbibliotek och Storybook) ska ligga i devDependencies – de behövs bara under utvecklingen och installeras inte från npm hos användarna. React ska ligga både i peerDependencies (krav vid körning) och devDependencies (behövs för att kompilera och testa biblioteket lokalt).

Deklarera React i peerDependencies (inte dependencies) så att användarna delar appens React-instans. sideEffects: false möjliggör fullständig tree-shaking av ert bibliotek. Använd sideEffects: ['*.css'] för att skydda CSS-importer från att tas bort. Namngivna exporter från enskilda filer ger maximal granularitet i tree-shaking. Upprätthåll en storleksbudget med size-limit i CI. Föredra CSS Modules framför CSS-in-JS i bibliotek för att undvika konflikter mellan peer dependencies.