Bundling with Rollup and tsup for Libraries

Vite's default configuration is optimized for applications — it bundles everything, handles assets, and generates an index.html. For a component library, you need a different output: pure ESM/CJS JavaScript files with no runtime overhead, no bundled React, and proper TypeScript declarations. Vite library mode works but Rollup and tsup are more purpose-built for this.

Rollup has been the standard bundler for JavaScript libraries for years. It produces clean, efficient output with excellent tree-shaking and supports both ESM and CJS output formats. Rollup's scope hoisting eliminates module wrapper overhead, producing the smallest possible library bundles.

tsup is a zero-config TypeScript bundler powered by esbuild. It is dramatically faster than Rollup (esbuild compiles in microseconds vs milliseconds). The minimal config: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } produces both module formats and TypeScript declarations automatically.

The core tsup options: entry is the array of entry point files. format specifies output formats: ['esm', 'cjs']. dts: true generates .d.ts TypeScript declaration files alongside the JS output. target sets the minimum JavaScript environment (esnext or es2020). splitting: false keeps output in single files.

esbuild (via tsup) compiles 10-100x faster than Rollup. Rollup produces slightly more optimized output with better tree-shaking granularity and more control over chunk boundaries. For most component libraries, tsup's speed wins in development. For maximum tree-shaking control or complex multi-entry setups, Rollup is preferred.

The most critical bundler configuration for a React library: never bundle React or ReactDOM. Mark them as external so they are excluded from your output. If your library bundles React, consumers will end up with two copies of React — one from your bundle and one from their app. This breaks all React hooks due to multiple React instances.

In tsup config, use the external option: external: ['react', 'react-dom']. In Rollup config, set external: ['react', 'react-dom', 'react/jsx-runtime']. Include react/jsx-runtime if your library uses JSX Transform. Also externalize any other peer dependencies your library declares.

A minimal Rollup config for a TypeScript library requires three plugins: @rollup/plugin-typescript for TypeScript compilation, @rollup/plugin-node-resolve to resolve node_modules imports, and @rollup/plugin-commonjs to convert CommonJS dependencies to ESM for the bundle. Add rollup-plugin-dts for declaration files.

A typical dual-format library output: dist/esm/index.js and dist/esm/index.d.ts for ESM consumers, dist/cjs/index.js and dist/cjs/index.cjs for CJS consumers. The package.json exports field maps these paths to the correct environments. TypeScript declaration files live alongside their JS counterparts.

Large libraries benefit from multiple entry points so consumers only import what they need. For example: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Each entry gets its own output files. The package.json exports field maps each public path to its output: './utils' → './dist/utils.js'.

Add the build command to package.json scripts: "build": "tsup". tsup reads its config from tsup.config.ts in the root. The prepublish script should run the build: "prepublishOnly": "npm run build" ensures your package is always built before publishing to npm.

Why must React be marked as external when bundling a React component library?

tsup (esbuild-powered) provides fast zero-config bundling with format: ['esm', 'cjs'] and dts: true. Rollup offers more fine-grained tree-shaking control with @rollup/plugin-typescript. The critical rule: always mark react, react-dom, and all peer dependencies as external to prevent bundling them. Output to dist/esm/ and dist/cjs/ with parallel TypeScript declarations. Multiple entry points enable granular tree-shaking for consumers.