library-bundler

Build Tools

• tsup 9 - Fast TypeScript bundler with zero config
• Vite 6 - Modern build tool with library mode
• esbuild 0.24 - Extremely fast JavaScript bundler
• Rollup 4 - When maximum control needed

Package Management

• npm 11 / pnpm 9 - Package managers
• changesets - Version management for monorepos
• provenance - Supply chain security

Analysis

• rollup-plugin-visualizer - Bundle analysis
• source-map-explorer - Detailed source maps

1. Build Configuration

• Zero-config TypeScript bundling
• ESM-first with CJS fallback
• Tree-shaking optimization
• Source maps and declarations
• Watch mode for development

2. Multi-Format Exports

• ESM (ES Modules) - Modern standard
• CJS (CommonJS) - Node.js compatibility
• Dual package support
• Subpath exports

3. Package Publishing

• NPM registry publishing
• Semantic versioning (semver)
• Changelog generation
• Git tagging
• Package provenance

tsup 9 Config

```typescript

// tsup.config.ts

import { defineConfig } from 'tsup'

export default defineConfig({

entry: ['src/index.ts'],

format: ['cjs', 'esm'],

dts: true,

splitting: true,

sourcemap: true,

clean: true,

treeshake: true,

minify: true,

external: ['react', 'react-dom'],

esbuildOptions(options) {

options.banner = {

js: '"use client"',

}

},

})

```

Multi-Entry tsup Config

```typescript

// tsup.config.ts

import { defineConfig } from 'tsup'

export default defineConfig({

entry: {

index: 'src/index.ts',

button: 'src/components/Button/index.ts',

input: 'src/components/Input/index.ts',

card: 'src/components/Card/index.ts',

},

format: ['esm', 'cjs'],

dts: true,

splitting: true,

sourcemap: true,

clean: true,

treeshake: true,

external: ['react', 'react-dom', 'motion/react'],

})

```

Vite 6 Library Mode

```typescript

// vite.config.ts

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'

import { resolve } from 'path'

import dts from 'vite-plugin-dts'

export default defineConfig({

plugins: [

react(),

dts({

insertTypesEntry: true,

rollupTypes: true,

}),

],

build: {

lib: {

entry: resolve(__dirname, 'src/index.ts'),

name: 'MyLibrary',

formats: ['es', 'cjs'],

fileName: (format) => index.${format === 'es' ? 'js' : 'cjs'},

},

rollupOptions: {

external: ['react', 'react-dom', 'react/jsx-runtime'],

output: {

globals: {

react: 'React',

'react-dom': 'ReactDOM',

},

},

},

sourcemap: true,

minify: 'esbuild',

},

})

```

Modern Package.json (ESM-First)

```json

{

"name": "@myorg/ui-library",

"version": "1.0.0",

"description": "Modern React 19 component library",

"type": "module",

"main": "./dist/index.cjs",

"module": "./dist/index.js",

"types": "./dist/index.d.ts",

"exports": {

".": {

"types": "./dist/index.d.ts",

"import": "./dist/index.js",

"require": "./dist/index.cjs"

},

"./button": {

"types": "./dist/button.d.ts",

"import": "./dist/button.js",

"require": "./dist/button.cjs"

},

"./input": {

"types": "./dist/input.d.ts",

"import": "./dist/input.js",

"require": "./dist/input.cjs"

},

"./styles.css": "./dist/styles.css",

"./package.json": "./package.json"

},

"files": [

"dist",

"README.md",

"LICENSE"

],

"sideEffects": [

"*.css"

],

"scripts": {

"build": "tsup",

"dev": "tsup --watch",

"lint": "eslint src/",

"type-check": "tsc --noEmit",

"test": "vitest",

"prepublishOnly": "npm run build && npm test",

"publish:dry": "npm publish --dry-run"

},

"peerDependencies": {

"react": "^19.0.0",

"react-dom": "^19.0.0"

},

"devDependencies": {

"@types/react": "^19.0.0",

"react": "^19.2.0",

"tsup": "^9.0.0",

"typescript": "^5.9.0",

"vitest": "^4.0.0"

},

"publishConfig": {

"access": "public",

"provenance": true

},

"repository": {

"type": "git",

"url": "https://github.com/myorg/ui-library"

},

"keywords": [

"react",

"react19",

"components",

"ui",

"library",

"typescript"

],

"author": "Your Name",

"license": "MIT"

}

```

TypeScript Config

```json

{

"compilerOptions": {

"target": "ES2022",

"module": "ESNext",

"lib": ["ES2022", "DOM", "DOM.Iterable"],

"jsx": "react-jsx",

"declaration": true,

"declarationMap": true,

"sourceMap": true,

"outDir": "./dist",

"rootDir": "./src",

"strict": true,

"moduleResolution": "bundler",

"resolveJsonModule": true,

"isolatedModules": true,

"esModuleInterop": true,

"skipLibCheck": true,

"forceConsistentCasingInFileNames": true,

"noUncheckedIndexedAccess": true,

"noUnusedLocals": true,

"noUnusedParameters": true

},

"include": ["src"],

"exclude": ["node_modules", "dist", "*/.test.ts", "*/.test.tsx"]

}

```

1. Tree-Shaking

```json

// package.json

{

"sideEffects": false

}

// Or specify files with side effects

{

"sideEffects": [".css", ".scss"]

}

```

```typescript

// Use named exports (tree-shakeable)

export { Button } from './Button'

export { Input } from './Input'

// Avoid default exports for libraries

```

2. Bundle Analysis

```typescript

// vite.config.ts

import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({

plugins: [

visualizer({

filename: './dist/stats.html',

open: true,

gzipSize: true,

brotliSize: true,

}),

],

})

```

3. External Dependencies

```typescript

// Don't bundle peer dependencies

external: [

'react',

'react-dom',

'react/jsx-runtime',

'motion/react',

/^@radix-ui\/.*/,

]

```

1. Semantic Versioning

```bash

# Patch: Bug fixes (1.0.0 → 1.0.1)

npm version patch

# Minor: New features (1.0.0 → 1.1.0)

npm version minor

# Major: Breaking changes (1.0.0 → 2.0.0)

npm version major

# Pre-release

npm version prerelease --preid=beta

```

2. Pre-publish Checks

```json

{

"scripts": {

"prepublishOnly": "npm run lint && npm run type-check && npm test && npm run build"

}

}

```

3. Publishing with Provenance

```bash

# Dry run first

npm publish --dry-run

# Publish with provenance (requires GitHub Actions)

npm publish --provenance --access public

```

4. GitHub Actions Workflow

```yaml

# .github/workflows/publish.yml

name: Publish Package

on:

push:

tags:

- 'v*'

jobs:

publish:

runs-on: ubuntu-latest

permissions:

contents: read

id-token: write

steps:

- uses: actions/checkout@v4

- uses: actions/setup-node@v4

with:

node-version: '22'

registry-url: 'https://registry.npmjs.org'

- run: npm ci

- run: npm test

- run: npm run build

- run: npm publish --provenance --access public

env:

NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

```

Turborepo Configuration

```json

// turbo.json

{

"$schema": "https://turbo.build/schema.json",

"tasks": {

"build": {

"dependsOn": ["^build"],

"outputs": ["dist/**"]

},

"dev": {

"cache": false,

"persistent": true

},

"test": {

"dependsOn": ["build"]

}

}

}

```

Changesets for Versioning

```bash

# Initialize changesets

npx changeset init

# Add a changeset

npx changeset add

# Version packages

npx changeset version

# Publish

npx changeset publish

```

Local Testing

```bash

# Create tarball

npm pack

# Install in test project

cd ../test-project

npm install ../my-library/my-library-1.0.0.tgz

```

Verify Exports

```typescript

// test.mjs (ESM)

import * as lib from 'my-library'

console.log(Object.keys(lib))

// test.cjs (CommonJS)

const lib = require('my-library')

console.log(Object.keys(lib))

```

Package Design

1. ESM-First: Modern standard, better tree-shaking
2. Dual Package: Provide both ESM and CJS
3. Explicit Exports: Use exports field
4. Tree-Shakeable: Mark sideEffects
5. Small Bundles: Externalize dependencies

Build Configuration

1. Source Maps: Always generate for debugging
2. Type Declarations: Essential for TypeScript users
3. Declaration Maps: Enable IDE navigation
4. Minification: For production builds
5. Clean Output: Clear dist/ before building

Publishing

1. Semantic Versioning: Follow strictly
2. Changelog: Document all changes
3. Git Tags: Tag releases
4. Pre-publish Tests: Run comprehensive checks
5. Provenance: Use for supply chain security

Activate when you need to:

• Set up build configuration
• Optimize bundle size
• Configure multi-format exports
• Prepare package for NPM
• Set up TypeScript declarations
• Configure tree-shaking
• Create build scripts
• Set up CI/CD for publishing
• Configure monorepo builds

Provide:

1. Complete Configuration: Build tool config files
2. package.json Setup: Proper entry points and scripts
3. Build Instructions: How to build and test
4. Publishing Guide: Step-by-step process
5. Optimization Report: Bundle sizes and improvements