Bundling con Rollup e tsup per le librerie

La configurazione predefinita di Vite è ottimizzata per le applicazioni: raggruppa tutto, gestisce gli asset e genera un index.html. Per una libreria di componenti serve un output diverso: file JavaScript puri in formato ESM/CJS, senza overhead a runtime, senza includere React nel bundle e con dichiarazioni TypeScript appropriate. La modalità libreria di Vite funziona, ma Rollup e tsup sono strumenti più specificamente progettati per questo scopo.

Rollup è da anni il bundler standard per le librerie JavaScript. Produce un output pulito ed efficiente, con un eccellente tree-shaking e supporto per i formati di output ESM e CJS. Lo scope hoisting di Rollup elimina l'overhead dei wrapper dei moduli e produce i bundle della libreria più piccoli possibili.

tsup è un bundler TypeScript senza configurazione, basato su esbuild. È molto più veloce di Rollup (esbuild compila in microsecondi anziché millisecondi). La configurazione minima: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } produce automaticamente entrambi i formati dei moduli e le dichiarazioni TypeScript.

Le opzioni principali di tsup: entry è l'array dei file di ingresso. format specifica i formati di output: ['esm', 'cjs']. dts: true genera file di dichiarazione TypeScript .d.ts accanto all'output JS. target imposta l'ambiente JavaScript minimo (esnext o es2020). splitting: false mantiene l'output in file singoli.

esbuild (tramite tsup) compila da 10 a 100 volte più velocemente di Rollup. Rollup produce un output leggermente più ottimizzato, con una granularità migliore del tree-shaking e un controllo maggiore sui limiti dei chunk. Per la maggior parte delle librerie di componenti, la velocità di tsup è un vantaggio durante lo sviluppo. Se serve il massimo controllo sul tree-shaking o configurazioni complesse con più entry point, si preferisce Rollup.

La configurazione più importante del bundler per una libreria React è: non includere mai React o ReactDOM nel bundle. Li imposti come external, in modo che vengano esclusi dall'output. Se la libreria include React nel bundle, chi la utilizza si ritroverà con due copie di React: una proveniente dal bundle e una dall'applicazione. Questo interrompe tutti gli hook di React a causa della presenza di più istanze di React.

Nella configurazione di tsup, utilizzi l'opzione external: external: ['react', 'react-dom']. Nella configurazione di Rollup, imposti external: ['react', 'react-dom', 'react/jsx-runtime']. Includa react/jsx-runtime se la libreria utilizza la trasformazione JSX. Renda external anche tutte le altre peer dependencies dichiarate dalla libreria.

Una configurazione Rollup minima per una libreria TypeScript richiede tre plugin: @rollup/plugin-typescript per la compilazione TypeScript, @rollup/plugin-node-resolve per risolvere gli import da node_modules e @rollup/plugin-commonjs per convertire le dipendenze CommonJS in ESM per il bundle. Aggiunga rollup-plugin-dts per i file di dichiarazione.

Un tipico output di una libreria in doppio formato comprende: dist/esm/index.js e dist/esm/index.d.ts per i consumer ESM, dist/cjs/index.js e dist/cjs/index.cjs per i consumer CJS. Il campo exports di package.json associa questi percorsi agli ambienti corretti. I file di dichiarazione TypeScript si trovano accanto ai corrispondenti file JS.

Le librerie di grandi dimensioni traggono vantaggio da più entry point, così i consumer importano solo ciò di cui hanno bisogno. Ad esempio: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Ogni entry genera i propri file di output. Il campo exports di package.json associa ogni percorso pubblico al relativo output: './utils' → './dist/utils.js'.

Aggiunga il comando di build agli script di package.json: "build": "tsup". tsup legge la propria configurazione da tsup.config.ts nella directory radice. Lo script prepublish deve eseguire la build: "prepublishOnly": "npm run build" assicura che il pacchetto venga sempre compilato prima della pubblicazione su npm.

Perché React deve essere impostato come external quando si crea il bundle di una libreria di componenti React?

tsup (basato su esbuild) offre un bundling rapido e senza configurazione, con format: ['esm', 'cjs'] e dts: true. Rollup offre un controllo più granulare sul tree-shaking con @rollup/plugin-typescript. La regola fondamentale è impostare sempre react, react-dom e tutte le peer dependencies come external per evitare di includerle nel bundle. Generi l'output in dist/esm/ e dist/cjs/, insieme alle dichiarazioni TypeScript corrispondenti. Più entry point consentono ai consumer un tree-shaking più granulare.