Bundlowanie bibliotek za pomocą Rollup i tsup

Domyślna konfiguracja Vite jest zoptymalizowana pod kątem aplikacji — pakuje wszystko, obsługuje zasoby i generuje plik index.html. Biblioteka komponentów wymaga innego formatu wyjściowego: czystych plików JavaScript ESM/CJS bez narzutu w czasie wykonywania, bez bundlowania Reacta oraz z prawidłowymi deklaracjami TypeScript. Tryb biblioteki Vite działa, ale Rollup i tsup są lepiej dostosowane do tego zastosowania.

Rollup od lat jest standardowym bundlerem dla bibliotek JavaScript. Generuje czysty i wydajny kod wyjściowy, zapewnia doskonały tree-shaking oraz obsługuje formaty wyjściowe ESM i CJS. Scope hoisting w Rollup eliminuje narzut opakowań modułów, tworząc możliwie najmniejsze paczki biblioteki.

tsup to niewymagający konfiguracji bundler TypeScript oparty na esbuild. Jest znacznie szybszy od Rollup, ponieważ esbuild kompiluje kod w mikrosekundach, a nie w milisekundach. Minimalna konfiguracja: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } automatycznie generuje oba formaty modułów oraz deklaracje TypeScript.

Najważniejsze opcje tsup: entry to tablica plików punktów wejścia. format określa formaty wyjściowe: ['esm', 'cjs']. dts: true generuje pliki deklaracji TypeScript .d.ts obok plików wyjściowych JS. target określa minimalne środowisko JavaScript (esnext lub es2020). splitting: false zachowuje dane wyjściowe w pojedynczych plikach.

esbuild (za pośrednictwem tsup) kompiluje od 10 do 100 razy szybciej niż Rollup. Rollup generuje nieco lepiej zoptymalizowany wynik, oferując większą szczegółowość tree-shakingu i większą kontrolę nad granicami chunków. W przypadku większości bibliotek komponentów szybkość tsup jest korzystniejsza podczas pracy deweloperskiej. Gdy potrzebna jest maksymalna kontrola nad tree-shakingiem lub złożona konfiguracja z wieloma punktami wejścia, preferowany jest Rollup.

Najważniejsza konfiguracja bundlera w przypadku biblioteki React: nigdy nie bundluj React ani ReactDOM. Oznacz je jako external, aby wykluczyć je z wynikowego kodu. Jeśli biblioteka bundluje React, użytkownik końcowy otrzyma dwie kopie Reacta — jedną z biblioteki i drugą ze swojej aplikacji. Powoduje to nieprawidłowe działanie wszystkich hooków React z powodu wielu instancji React.

W konfiguracji tsup użyj opcji external: external: ['react', 'react-dom']. W konfiguracji Rollup ustaw external: ['react', 'react-dom', 'react/jsx-runtime']. Uwzględnij react/jsx-runtime, jeśli biblioteka korzysta z JSX Transform. Oznacz jako external także wszystkie inne peer dependencies zadeklarowane przez bibliotekę.

Minimalna konfiguracja Rollup dla biblioteki TypeScript wymaga trzech wtyczek: @rollup/plugin-typescript do kompilowania TypeScript, @rollup/plugin-node-resolve do rozwiązywania importów z node_modules oraz @rollup/plugin-commonjs do konwertowania zależności CommonJS na ESM w bundlu. Dodaj rollup-plugin-dts do obsługi plików deklaracji.

Typowy wynik biblioteki w dwóch formatach obejmuje: dist/esm/index.js i dist/esm/index.d.ts dla odbiorców ESM oraz dist/cjs/index.js i dist/cjs/index.cjs dla odbiorców CJS. Pole exports w package.json mapuje te ścieżki na właściwe środowiska. Pliki deklaracji TypeScript znajdują się obok odpowiadających im plików JS.

Duże biblioteki zyskują na wielu punktach wejścia, ponieważ odbiorcy importują tylko to, czego potrzebują. Przykład: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Każdy punkt wejścia otrzymuje własne pliki wynikowe. Pole exports w package.json mapuje każdą publiczną ścieżkę na odpowiedni wynik: './utils' → './dist/utils.js'.

Dodaj polecenie kompilowania do sekcji scripts w package.json: "build": "tsup". tsup odczytuje konfigurację z tsup.config.ts znajdującego się w katalogu głównym. Skrypt prepublish powinien uruchamiać kompilowanie: "prepublishOnly": "npm run build" gwarantuje, że pakiet zostanie zawsze zbudowany przed opublikowaniem w npm.

Dlaczego podczas bundlowania biblioteki komponentów React należy oznaczyć React jako external?

tsup (oparty na esbuild) zapewnia szybkie bundlowanie bez konfiguracji, z ustawieniami format: ['esm', 'cjs'] i dts: true. Rollup oferuje bardziej szczegółową kontrolę nad tree-shakingiem dzięki @rollup/plugin-typescript. Najważniejsza zasada: zawsze oznaczaj react, react-dom i wszystkie peer dependencies jako external, aby nie bundlować ich z biblioteką. Generuj wynik w dist/esm/ i dist/cjs/ wraz z równoległymi deklaracjami TypeScript. Wiele punktów wejścia umożliwia odbiorcom precyzyjny tree-shaking.