Rollup.js Technical Reference - AI-Optimized

Core Technology Overview

Primary Function: JavaScript module bundler optimized for ES modules with genuine tree-shaking capabilities

Key Differentiator: Built specifically for ES modules from inception, unlike retrofitted solutions

Critical Performance Characteristics

Tree-Shaking Effectiveness

• Actually functional: Removes unused code unlike Webpack's claimed tree-shaking
• Quantified impact: Import single function = bundle single function (vs Webpack bundling code chunks)
• Breaking conditions:
  • Barrel exports (index.js re-exporting 50+ modules)
  • CommonJS modules (plugin helps but limited)
  • Dynamic exports
  • Incorrect lodash imports (use lodash-es or individual imports: import { debounce } from 'lodash-es')

Build Performance Reality

• Rollup: 2-8 seconds for production builds
• Webpack: Significantly slower (lunch break duration for large codebases)
• esbuild: Sub-second but less optimization
• Memory requirements: Standard RAM vs Webpack's 32GB requirement for enterprise codebases

Configuration Requirements

Essential Plugins (Mandatory)

// Critical plugin order - resolve() BEFORE commonjs() or silent failures
plugins: [
  resolve(),    // Find node_modules dependencies
  commonjs(),   // Handle legacy CommonJS (sometimes fails)
  typescript(), // TypeScript support
  terser()      // Minification
]

Production-Ready Configuration

export default [
  // ES modules output
  {
    input: 'src/index.ts',
    output: { file: 'dist/index.esm.js', format: 'esm' },
    external: ['react', 'lodash'], // CRITICAL: Prevent bundling dependencies
    plugins: [resolve(), commonjs(), typescript()]
  },
  // CommonJS compatibility
  {
    input: 'src/index.ts',
    output: { file: 'dist/index.cjs.js', format: 'cjs' },
    external: ['react', 'lodash'],
    plugins: [resolve(), commonjs(), typescript(), terser()]
  }
];

Critical Failure Modes

Plugin Compatibility Issues

• Plugin order dependency: Incorrect order causes silent build failures
• Version conflicts: Major Rollup updates break plugins without migration guides
• Example failure: CommonJS plugin v22.x has memory leaks with large modules
• Real incident: Rollup 3.2.0 broke CI pipelines due to externals changes

CommonJS Integration Failures

• react-dom: Notorious for plugin compatibility issues
• Material-UI v4: Weird exports cause plugin failures
• Resolution: Find ES module alternatives or different packages

Circular Dependency Consequences

• Behavior: Spam warnings until fixed
• Real impact: Wrong module load order in production
• Example: Redux store circular import caused production failure

Resource Requirements

Development Setup

• Dev server: None (requires browser refresh)
• Recommendation: Use Vite for development (uses Rollup for production)
• Time cost: 2019-era development experience without hot reload

Expertise Requirements

• Plugin configuration: Complex, order-dependent
• TypeScript integration: Plugin ignores some tsconfig.json settings
• Bundle analysis: Requires rollup-plugin-visualizer for debugging

Decision Matrix

Use Case	Rollup Suitability	Alternative Recommendation
npm Libraries	Perfect - Vue, React Router, D3 use it	None
Small-Medium Apps	Good - If bundle size critical	Vite (uses Rollup internally)
Large Applications	Avoid - Lacks tooling ecosystem	Webpack, Next.js/Nuxt
Development	Avoid - No HMR, constant refresh	Vite
Quick Prototypes	Avoid - Too much configuration	Parcel

Critical Warnings

What Documentation Doesn't Tell You

• Watch mode performance: Rebuilds everything, not incremental
• Plugin ecosystem fragility: Updates break compatibility frequently
• Memory leaks: CommonJS plugin v22.x with large modules
• TypeScript gotchas: Declaration files in wrong directories, no incremental compilation

Breaking Points

• UI failure threshold: 1000+ spans make debugging impossible
• Bundle size explosion: Single bad import can add 200KB unused code
• Build failure scenarios: Plugin version mismatches, circular dependencies, external configuration errors

Implementation Success Patterns

Library Publishing

// Proven configuration for npm packages
external: ['react', 'lodash'], // Mark peer dependencies as external
output: [
  { format: 'esm' },  // Modern consumption
  { format: 'cjs' }   // Legacy compatibility
]

Bundle Size Optimization

• Use rollup-plugin-visualizer immediately
• Check Bundle Phobia before importing packages
• Prefer lodash-es over lodash
• Mark all peer dependencies as external

TypeScript Integration

typescript({
  declaration: true,        // Generate .d.ts files
  declarationDir: 'dist',  // Specify output location
  exclude: ['**/*.test.ts'] // Don't bundle tests
})

Operational Intelligence

When Rollup Actually Makes Sense

1. Publishing npm libraries - Industry standard (Vue, React Router, D3)
2. Bundle size is critical - Genuine tree-shaking advantage
3. Simple to medium complexity - Before tooling requirements explode

When to Use Alternatives

• Need dev server: Use Vite (Rollup for prod, esbuild for dev)
• Complex asset processing: Use Webpack
• Large team/codebase: Use established toolchain (Next.js, Nuxt)
• Quick prototyping: Use Parcel

Survival Strategies

• Pin plugin versions in production
• Test updates in separate branches
• Always use bundle visualization
• Maintain external dependencies list
• Use Vite wrapper for modern development experience

Resource Investment Reality

Time Costs

• Initial setup: 2-4 hours for proper configuration
• Plugin debugging: 3+ hours when CommonJS plugin fails
• Circular dependency fixes: Variable (architectural changes required)
• Update cycles: High maintenance due to plugin compatibility

Expertise Requirements

• ES modules understanding (mandatory)
• Plugin ecosystem knowledge
• Bundle analysis skills
• Alternative bundler awareness for migration paths