Rollup Production Troubleshooting: AI-Optimized Guide

Critical Memory Issues

JavaScript Heap Out of Memory

Failure Mode: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
Impact: Kills builds completely for large codebases
Quick Fix: NODE_OPTIONS="--max-old-space-size=8192" npm run build
Permanent Solution: Add to package.json scripts
Root Causes:

• Large TypeScript projects with complex type checking
• Circular dependencies creating memory loops
• Bad plugins not cleaning up properly
• Processing massive files (15MB+ JSON imports)

Build Hangs at 90% Completion

Symptoms: Build shows progress then freezes with no error output
Nuclear Option: rm -rf node_modules package-lock.json && npm install && npm run build (works 90% of time)
Smart Debugging: Use madge --circular --format es6 src/ to detect circular dependencies
Common Causes:

• Circular imports creating infinite loops
• Plugin conflicts (especially TypeScript + Babel)
• Corrupted node_modules cache
• File watchers on Windows getting confused

Bundle Size Explosions

Immediate Diagnosis Tool

Essential Plugin: rollup-plugin-visualizer

import { visualizer } from 'rollup-plugin-visualizer';
plugins: [
  visualizer({
    filename: 'dist/stats.html',
    open: true,
    gzipSize: true
  })
]

Common Size Killers

• moment.js import: Adds 500KB (use date-fns instead)
• Wrong lodash import: import _ from 'lodash' vs import { debounce } from 'lodash-es'
• Dev dependency leak: Check external configuration
• Broken tree-shaking: Side effects not properly marked

Real Impact: Bundle went from 300KB to 3MB, site became unusable until fixed

Plugin Configuration Hell

Working Plugin Order (95% of projects)

plugins: [
  resolve({ preferBuiltins: false }),
  commonjs(),
  typescript(),
  babel(), 
  terser() // Always last
]

Plugin Conflict Debugging Strategy

1. Create minimal config with single plugin
2. Add plugins one by one until failure
3. Test in isolation with separate config file

Known Plugin Issues

• @rollup/plugin-commonjs: Gives up on weird packages (react-dom)
• @rollup/plugin-typescript: Ignores half of tsconfig.json settings
• rollup-plugin-postcss: Breaks with CSS modules sometimes
• @rollup/plugin-json: Crashes on huge JSON files

CI/CD Failures

GitHub Actions Memory Issues

Solution: NODE_OPTIONS="--max-old-space-size=4096" npm run build
Root Cause: GitHub Actions default runners have memory limitations

Vercel Deployment Failures

Limit: 250MB for entire build directory
Check: du -sh dist/ to verify size locally

Docker Build Issues

FROM node:18-alpine
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN npm run build

Source Map Problems

Production Configuration

output: {
  sourcemap: true,
  sourcemapExcludeSources: true  // Don't leak source code
}

Debugging Production Errors

Tool: smc --source-map dist/bundle.js.map --line 1 --column 47293
Integration: Sentry or Bugsnag for automated error tracking

Crisis Mode Solutions

Build Works Locally, Fails in CI

Primary Suspects: Node version differences, environment variables, dependency cache
Quick Fixes:

• Lock Node version with .nvmrc
• Clear CI cache: rm -rf node_modules package-lock.json && npm ci
• Check environment differences: env | grep NODE
  Root Cause 90% of time: Different dependencies (someone used npm install instead of npm ci)

Bundle Loads But App Crashes

Diagnosis: Tree-shaking removed needed code or wrong module loading order
Quick Test: Set treeshake: false temporarily
Look For:

• Side effects in imported modules
• Dynamic imports Rollup can't analyze
• Circular dependencies confusing module order

Memory Usage Growing on Rebuilds

Symptom: First build 2GB RAM, second build 4GB, eventually crashes
Known Issue: Rollup watch mode with certain plugins
Workarounds:

• Use Vite for development, Rollup for production
• Restart build process periodically
• NODE_OPTIONS="--max-old-space-size=8192"

Module Not Found But File Exists

Usual Cause: Path resolution broken or mixing module systems
Debug Steps:

resolve({
  preferBuiltins: false,
  browser: true,
  exportConditions: ['svelte']  // Adjust for framework
})

Check: Import paths, case sensitivity, missing file extensions

Advanced Debugging Techniques

Bundle Analysis Tools (Use All)

1. rollup-plugin-visualizer: Size relationships
2. webpack-bundle-analyzer: Interactive treemap
3. Bundle Buddy: Explains why modules included

Memory Profiling

Heap Snapshots: node --inspect-brk node_modules/.bin/rollup -c
Memory Leak Detection: Use memwatch-next for monitoring
Real Example: 12GB RAM usage reduced to 2GB by updating TypeScript plugin

Performance Profiling

Build Time: ROLLUP_WATCH_INCLUDE_TIME=1 rollup -c --watch
Plugin Timing: Wrap plugins with timing measurements
Bottleneck Identification: Usually TypeScript or large file processing

Dependency Hell

Version Conflicts: npm ls --depth=0 | grep -E "├─|└─" | sort
Force Resolutions: Use overrides in package.json as last resort
Real Example: Three @babel/core versions caused random build failures

Production Runtime Errors

Source Map Debugging

1. Deploy source maps to private URL
2. Add source map comment to production bundle
3. Use Chrome DevTools with source maps enabled

Error Tracking Integration

replace({
  '__BUILD_DATE__': JSON.stringify(new Date().toISOString()),
  '__GIT_COMMIT__': JSON.stringify(process.env.GIT_COMMIT || 'unknown')
})

Emergency Debugging

Chrome Works, Safari/Firefox Breaks

Cause: Modern JavaScript features need polyfills
Fix: Configure Babel with browser targets
Common Culprits: Optional chaining, nullish coalescing, dynamic imports

Slow Build Performance

1. Parallel Processing: Enable TypeScript transpileOnly, use all CPU cores for Terser
2. Split Build: Type check separately from bundling
3. Cache Everything: Enable Rollup cache, TypeScript incremental builds
   Nuclear Option: Use SWC instead of Babel (20x faster)

Code Splitting 404s

Problem: New chunk names, old chunks deleted
Solutions:

• Stable chunk names: [name]-[hash].js
• Manual chunks for vendor libraries
• CDN cache invalidation after deploy

Plugin "Cannot Find Module"

First Try: Restart dev server (plugin resolution caches aggressive)
Nuclear Option: rm -rf node_modules package-lock.json .rollup.cache && npm install
Check: Plugin version compatibility

Wrong Source Map Lines

Cause: Minification scrambling mappings
Fix: Generate source maps at each transformation step
Debug: Use source-map-cli to validate mappings

Missing Features in Production

Cause: Tree-shaking killed important code
Quick Test: Set moduleSideEffects: true
Proper Fix: Mark side effects in package.json

"ReferenceError: exports is not defined"

Problem: Mixing CommonJS and ES modules incorrectly
Fix: Configure CommonJS plugin to only convert node_modules
Alternative: Convert everything to ES modules

Resource Requirements

Memory Allocation

• Development: 2-4GB sufficient for most projects
• Large Projects: 8GB+ required (TypeScript, large dependencies)
• CI Environments: 4GB recommended minimum

Build Time Expectations

• Small Projects (<100 files): 10-30 seconds
• Medium Projects (100-1000 files): 1-5 minutes
• Large Projects (1000+ files): 5-15 minutes
• Performance Issues: >15 minutes indicates problems

Expertise Requirements

• Basic Setup: Junior developer can handle with documentation
• Plugin Configuration: Mid-level developer needed
• Performance Optimization: Senior developer required
• Memory Debugging: Expert-level Node.js knowledge needed

Critical Warnings

Production Deployment

• Never commit without testing: Rollup's tree-shaking can break functionality
• Always run linting/type checking: Build success doesn't guarantee code quality
• Monitor bundle size: Set automated alerts for size increases
• Test in target browsers: Chrome success doesn't guarantee cross-browser compatibility

Configuration Pitfalls

• Plugin order matters: Wrong order causes mysterious failures
• Tree-shaking aggressive: Can remove needed code unexpectedly
• Source maps leak source: Use sourcemapExcludeSources in production
• Memory limits hit suddenly: Node.js default heap insufficient for large projects

Breaking Points

• >1000 TypeScript files: Memory issues likely without optimization
• >250MB build output: Vercel deployment fails
• Circular dependencies: Cause infinite loops and memory leaks
• Mixed module systems: CommonJS/ES modules mixing breaks builds

Decision Criteria

When to Use Rollup

• Library bundling: Excellent tree-shaking and ES module output
• Production optimization: Superior dead code elimination
• Plugin ecosystem: Extensive plugin availability

When to Avoid Rollup

• Large applications: Webpack better for app bundling
• Development speed priority: Vite/esbuild much faster
• Team expertise low: Steeper learning curve than alternatives

Alternative Considerations

• Vite: Better development experience, uses Rollup for production
• esbuild: Much faster, less optimization
• Webpack: Better for large applications, more mature ecosystem
• SWC: Rust-based, extremely fast, growing ecosystem

Emergency Resources

Essential Tools

• rollup-plugin-visualizer: Bundle size analysis
• Bundle Buddy: Module inclusion analysis
• madge: Circular dependency detection
• source-map-cli: Source map debugging
• npm-check-updates: Dependency updates

Documentation

• Rollup Troubleshooting Guide: Official configuration issues
• Plugin Development Guide: Understanding plugin conflicts
• Node.js Memory Management: Debugging memory problems
• Chrome DevTools Memory: Profiling memory usage

Community Support

• Rollup Discord: Real-time help for urgent issues
• Stack Overflow: Search existing solutions first
• GitHub Issues: Most problems already reported and solved