Mit Rollup und tsup für Bibliotheken bundlen

Die Standardkonfiguration von Vite ist für Anwendungen optimiert: Sie bündelt alles, verarbeitet Assets und erzeugt eine index.html. Für eine Komponentenbibliothek benötigen Sie eine andere Ausgabe: reine ESM-/CJS-JavaScript-Dateien ohne Laufzeit-Overhead, ohne gebündeltes React und mit ordnungsgemäßen TypeScript-Deklarationen. Der Bibliotheksmodus von Vite funktioniert zwar, aber Rollup und tsup sind dafür besser geeignet.

Rollup ist seit Jahren der Standard-Bundler für JavaScript-Bibliotheken. Es erzeugt eine übersichtliche, effiziente Ausgabe mit ausgezeichnetem Tree-Shaking und unterstützt sowohl das ESM- als auch das CJS-Ausgabeformat. Rollups Scope Hoisting beseitigt den Overhead von Modul-Wrappern und erzeugt so die kleinstmöglichen Bibliotheks-Bundles.

tsup ist ein TypeScript-Bundler ohne Konfiguration, der von esbuild unterstützt wird. Er ist deutlich schneller als Rollup (esbuild kompiliert in Mikrosekunden statt in Millisekunden). Die minimale Konfiguration: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } erzeugt automatisch beide Modulformate und TypeScript-Deklarationen.

Die wichtigsten tsup-Optionen: entry ist das Array der Dateien mit den Einstiegspunkten. format legt die Ausgabeformate fest: ['esm', 'cjs']. dts: true erzeugt .d.ts-TypeScript-Deklarationsdateien neben der JS-Ausgabe. target legt die minimale JavaScript-Umgebung fest (esnext oder es2020). splitting: false hält die Ausgabe in einzelnen Dateien.

esbuild (über tsup) kompiliert 10- bis 100-mal schneller als Rollup. Rollup erzeugt eine etwas stärker optimierte Ausgabe mit einer feineren Tree-Shaking-Granularität und mehr Kontrolle über Chunk-Grenzen. Für die meisten Komponentenbibliotheken überwiegt beim Entwickeln die Geschwindigkeit von tsup. Für maximale Kontrolle über das Tree-Shaking oder komplexe Setups mit mehreren Einstiegspunkten wird Rollup bevorzugt.

Die wichtigste Bundler-Konfiguration für eine React-Bibliothek: React oder ReactDOM niemals bündeln. Markieren Sie beide als extern, damit sie aus Ihrer Ausgabe ausgeschlossen werden. Wenn Ihre Bibliothek React bündelt, haben Nutzer am Ende zwei Kopien von React — eine aus Ihrem Bundle und eine aus ihrer App. Dadurch funktionieren alle React-Hooks aufgrund mehrerer React-Instanzen nicht mehr.

Verwenden Sie in der tsup-Konfiguration die Option external: external: ['react', 'react-dom']. Setzen Sie in der Rollup-Konfiguration external: ['react', 'react-dom', 'react/jsx-runtime']. Beziehen Sie react/jsx-runtime ein, wenn Ihre Bibliothek den JSX Transform verwendet. Machen Sie außerdem alle anderen Peer-Abhängigkeiten, die Ihre Bibliothek deklariert, extern.

Eine minimale Rollup-Konfiguration für eine TypeScript-Bibliothek benötigt drei Plugins: @rollup/plugin-typescript für die TypeScript-Kompilierung, @rollup/plugin-node-resolve zum Auflösen von Importen aus node_modules und @rollup/plugin-commonjs, um CommonJS-Abhängigkeiten für das Bundle in ESM umzuwandeln. Fügen Sie rollup-plugin-dts für Deklarationsdateien hinzu.

Eine typische Ausgabe einer Bibliothek in zwei Formaten: dist/esm/index.js und dist/esm/index.d.ts für ESM-Nutzer sowie dist/cjs/index.js und dist/cjs/index.cjs für CJS-Nutzer. Das package.json-Feld exports ordnet diese Pfade den richtigen Umgebungen zu. TypeScript-Deklarationsdateien liegen neben ihren entsprechenden JS-Dateien.

Große Bibliotheken profitieren von mehreren Einstiegspunkten, damit Nutzer nur das importieren, was sie benötigen. Beispiel: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Für jeden Einstiegspunkt werden eigene Ausgabedateien erstellt. Das exports-Feld von package.json ordnet jeden öffentlichen Pfad seiner Ausgabe zu: './utils' → './dist/utils.js'.

Fügen Sie den Build-Befehl den scripts in package.json hinzu: "build": "tsup". tsup liest seine Konfiguration aus tsup.config.ts im Stammverzeichnis. Das prepublish-Skript sollte den Build ausführen: "prepublishOnly": "npm run build" stellt sicher, dass Ihr Paket vor der Veröffentlichung bei npm immer gebaut wird.

Warum muss React beim Bündeln einer React-Komponentenbibliothek als extern markiert werden?

tsup (auf esbuild-Basis) bietet schnelles Bundling ohne Konfiguration mit format: ['esm', 'cjs'] und dts: true. Rollup ermöglicht mit @rollup/plugin-typescript eine feingranularere Kontrolle über das Tree-Shaking. Die wichtigste Regel: Markieren Sie react, react-dom und alle Peer-Abhängigkeiten immer als extern, damit sie nicht gebündelt werden. Geben Sie die Dateien in dist/esm/ und dist/cjs/ zusammen mit den entsprechenden TypeScript-Deklarationen aus. Mehrere Einstiegspunkte ermöglichen Nutzern ein feingranulares Tree-Shaking.