Zależności peer i tree shaking

Peer dependencies deklarują pakiety wymagane przez bibliotekę, ale dostarczane przez odbiorcę. W package.json biblioteki React powinien znajdować się w sekcji peerDependencies, a nie dependencies. Gdy użytkownik instaluje bibliotekę, npm/yarn nie instaluje automatycznie React — aplikacja użytkownika ma już React, a biblioteka korzysta z tej samej instancji.

Jeśli React znajduje się w dependencies biblioteki, npm może zainstalować drugą kopię Reacta obok Reacta odbiorcy. Dwie instancje React w tej samej aplikacji powodują nieprawidłowe działanie wszystkich hooków i błąd „Invalid hook call”. Deklarując React jako peerDependency, informujesz npm: „Potrzebuję React, ale użyj tego, który odbiorca już ma”.

Niektóre peer dependencies mogą być opcjonalne — na przykład biblioteka obsługująca zarówno styled-components, jak i CSS Modules. Oznacz opcjonalne peer dependencies za pomocą peerDependenciesMeta: { 'styled-components': { optional: true } }. npm nie będzie ostrzegać użytkowników o brakujących opcjonalnych peer dependencies, ale typy TypeScript nadal mogą być dostępne po zainstalowaniu opcjonalnego pakietu.

Pole sideEffects w package.json informuje bundlery, czy biblioteka może bezpiecznie podlegać tree-shakingowi. Ustawienie "sideEffects": false informuje webpack, Rollup i podobne narzędzia, że importowanie dowolnego modułu biblioteki nie powoduje efektów ubocznych — wszystkie nieużywane eksporty można bezpiecznie usunąć z bundla odbiorcy.

Importy CSS są częstym efektem ubocznym — wstrzykują style do strony jako skutek importowania. Jeśli biblioteka importuje pliki CSS, ustaw "sideEffects": ["*.css", "*.scss"], aby poinformować bundlery, że pliki JS można bezpiecznie poddać tree-shakingowi, ale pliki CSS muszą zawsze zostać dołączone po zaimportowaniu.

Aby uzyskać maksymalną skuteczność tree-shakingu, eksportuj każdy komponent jako eksport nazwany z własnego pliku. W pliku index.ts ponownie eksportuj wszystko: export { Button } from './Button'. Gdy odbiorca importuje tylko Button, bundler może usunąć wszystkie pozostałe komponenty. Pliki zbiorcze z ponownymi eksportami umożliwiają stosowanie tego wzorca.

Użyj bundlejs.com, aby przetestować tree-shaking: wklej instrukcję importu, a narzędzie podaje rzeczywisty rozmiar bundla. Pakiet npm size-limit pozwala zdefiniować limity rozmiaru w package.json i przerwać CI, jeśli rozmiar importu przekroczy limit: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Ustal budżet rozmiaru dla importów biblioteki. Uruchamiaj npx size-limit w CI, aby go egzekwować. Wzrost wpływu bundla z czasem wskazuje na rozszerzanie zakresu biblioteki. Skoncentrowana biblioteka komponentów powinna utrzymywać importy pojedynczych komponentów na poziomie kilku kilobajtów. Wykrywaj regresje, zanim dotrą do odbiorców.

Unikaj styled-components i Emotion w bibliotekach komponentów przeznaczonych do dystrybucji. Te rozwiązania CSS-in-JS działające w czasie wykonywania wymagają od odbiorcy zainstalowania tej samej biblioteki i wersji, co prowadzi do konfliktów peer dependencies. Nawet jeśli odbiorca używa Tailwind lub zwykłego CSS, nadal musi bundlować środowisko uruchomieniowe CSS-in-JS. Preferuj CSS Modules, które podczas kompilowania są przekształcane w zwykły CSS.

CSS Modules dobrze sprawdzają się w bibliotekach w połączeniu z bundlerem, który je przetwarza. tsup i Rollup mogą osadzić wynik CSS Modules jako nazwy klas o ograniczonym zasięgu. Odbiorca nie musi niczego konfigurować — style są już ograniczone do właściwego zakresu i dołączone do bundla JS albo umieszczone w osobnym pliku CSS, który jest importowany.

Własne narzędzia deweloperskie (tsup, TypeScript, biblioteki do testowania i Storybook) umieść w devDependencies — są potrzebne tylko podczas tworzenia i nie są instalowane przez npm u odbiorców. React umieść zarówno w peerDependencies (wymaganie środowiska uruchomieniowego), jak i w devDependencies (jest potrzebny do lokalnego kompilowania i testowania biblioteki).

Zadeklaruj React w peerDependencies (a nie dependencies), aby odbiorcy korzystali z instancji React ze swojej aplikacji. sideEffects: false umożliwia pełny tree-shaking biblioteki. Użyj sideEffects: ['*.css'], aby ochronić importy CSS przed usunięciem. Eksporty nazwane z osobnych plików zapewniają maksymalną szczegółowość tree-shakingu. Egzekwuj budżet rozmiaru za pomocą size-limit w CI. W bibliotekach preferuj CSS Modules zamiast CSS-in-JS, aby uniknąć konfliktów peer dependencies.