Regrouper avec Rollup et tsup pour les bibliothèques

La configuration par défaut de Vite est optimisée pour les applications : elle regroupe tout, gère les ressources et génère un index.html. Pour une bibliothèque de composants, vous avez besoin d’un résultat différent : des fichiers JavaScript ESM/CJS purs, sans surcharge à l’exécution, sans React regroupé et avec des déclarations TypeScript correctes. Le mode bibliothèque de Vite fonctionne, mais Rollup et tsup sont davantage conçus pour cela.

Rollup est depuis des années l’outil de regroupement de référence pour les bibliothèques JavaScript. Il produit un résultat propre et efficace, avec une excellente élimination des modules inutilisés, et prend en charge les formats de sortie ESM et CJS. La remontée de portée de Rollup élimine la surcharge des enveloppes de modules et produit les ensembles de fichiers de bibliothèque les plus petits possibles.

tsup est un outil de regroupement TypeScript sans configuration, propulsé par esbuild. Il est considérablement plus rapide que Rollup (esbuild compile en microsecondes, contre des millisecondes). La configuration minimale : { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } génère automatiquement les deux formats de modules et les déclarations TypeScript.

Les principales options de tsup sont les suivantes : entrée est le tableau des fichiers de point d’entrée. format indique les formats de sortie : ['esm', 'cjs']. dts : vrai génère les fichiers de déclaration TypeScript .d.ts en parallèle de la sortie JS. cible définit l’environnement JavaScript minimal (esnext ou es2020). découpage : faux conserve la sortie dans des fichiers uniques.

esbuild (par l’intermédiaire de tsup) compile 10 à 100 fois plus vite que Rollup. Rollup produit une sortie légèrement mieux optimisée, avec une granularité plus fine de l’élimination du code inutilisé et davantage de contrôle sur les limites des fragments. Pour la plupart des bibliothèques de composants, la rapidité de tsup l’emporte en développement. Pour un contrôle maximal de l’élimination du code inutilisé ou des configurations complexes à plusieurs points d’entrée, Rollup est préférable.

La configuration la plus importante de l’outil de regroupement pour une bibliothèque React est la suivante : ne regroupez jamais React ni ReactDOM. Déclarez-les comme externes afin de les exclure de votre sortie. Si votre bibliothèque regroupe React, les utilisateurs se retrouveront avec deux copies de React : une provenant de votre paquet et l’autre de leur application. Cela casse tous les points d’ancrage de React à cause de la présence de plusieurs instances de React.

Dans la configuration de tsup, utilisez l’option external : external: ['react', 'react-dom']. Dans la configuration de Rollup, définissez external: ['react', 'react-dom', 'react/jsx-runtime']. Incluez react/jsx-runtime si votre bibliothèque utilise la transformation JSX. Déclarez également comme externes toutes les autres dépendances entre pairs déclarées par votre bibliothèque.

Une configuration Rollup minimale pour une bibliothèque TypeScript nécessite trois modules complémentaires : @rollup/plugin-typescript pour compiler TypeScript, @rollup/plugin-node-resolve pour résoudre les importations depuis node_modules et @rollup/plugin-commonjs pour convertir les dépendances CommonJS en ESM dans le paquet. Ajoutez rollup-plugin-dts pour les fichiers de déclaration.

Une sortie typique pour une bibliothèque proposant deux formats : dist/esm/index.js et dist/esm/index.d.ts pour les utilisateurs d’ESM, dist/cjs/index.js et dist/cjs/index.cjs pour les utilisateurs de CJS. Le champ exports de package.json associe ces chemins aux environnements appropriés. Les fichiers de déclaration TypeScript se trouvent à côté de leurs équivalents JS.

Les grandes bibliothèques ont intérêt à proposer plusieurs points d’entrée afin que les utilisateurs n’importent que ce dont ils ont besoin. Par exemple : entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Chaque point d’entrée produit ses propres fichiers de sortie. Le champ exports de package.json associe chaque chemin public à sa sortie : './utils' → './dist/utils.js'.

Ajoutez la commande de compilation aux scripts de package.json : "build": "tsup". tsup lit sa configuration dans tsup.config.ts à la racine. Le script de prépublication doit lancer la compilation : "prepublishOnly": "npm run build" garantit que votre paquet est toujours compilé avant sa publication sur npm.

Pourquoi React doit-il être déclaré comme externe lors du regroupement d’une bibliothèque de composants React ?

tsup (propulsé par esbuild) fournit un regroupement rapide sans configuration, avec format: ['esm', 'cjs'] et dts: true. Rollup offre un contrôle plus fin de l’élimination du code inutilisé avec @rollup/plugin-typescript. La règle essentielle : déclarez toujours react, react-dom et toutes les dépendances entre pairs comme externes pour éviter de les regrouper. Produisez les sorties dans dist/esm/ et dist/cjs/ avec les déclarations TypeScript correspondantes. Plusieurs points d’entrée permettent aux utilisateurs une élimination plus fine du code inutilisé.