Common Rollup Issues and Solutions

1. Build Fails Due to Unexpected Token Errors

Rollup fails with syntax errors, such as "Unexpected token" when processing files.

Root Causes:

• Using modern syntax (e.g., JSX, TypeScript) without the appropriate Rollup plugins.
• Incorrectly configured Babel or TypeScript settings.
• Trying to bundle non-JavaScript assets (e.g., CSS, JSON) without proper handling.

Solution:

Ensure the necessary plugins are installed:

npm install --save-dev @rollup/plugin-babel @rollup/plugin-typescript

Modify rollup.config.js to support JSX and TypeScript:

import babel from "@rollup/plugin-babel";import typescript from "@rollup/plugin-typescript";export default {  input: "src/index.tsx",  output: {    file: "dist/bundle.js",    format: "esm"  },  plugins: [typescript(), babel({ babelHelpers: "bundled" })]};

For non-JavaScript assets, add appropriate plugins:

npm install --save-dev @rollup/plugin-json @rollup/plugin-url

2. Tree-Shaking Not Working Properly

Rollup fails to eliminate unused code, leading to larger-than-expected bundles.

Root Causes:

• ES modules not being used properly (e.g., CommonJS imports).
• Side-effects not marked correctly in package.json.
• Improperly configured Rollup settings.

Solution:

Ensure you are importing only the required functions:

import { specificFunction } from "./utils";

Mark side-effect-free packages in package.json:

{  "sideEffects": false}

Use Rollup’s built-in tree-shaking analysis:

rollup --config --verbose

3. External Dependencies Are Bundled Instead of Being Excluded

Rollup incorrectly includes external dependencies in the final bundle.

Root Causes:

• External dependencies not explicitly marked in Rollup config.
• Incorrect module resolution settings.
• Improper handling of peer dependencies.

Solution:

Mark external dependencies in rollup.config.js:

export default {  input: "src/index.js",  external: ["react", "react-dom"],  output: {    file: "dist/bundle.js",    format: "esm"  }};

Use peerDependencies instead of dependencies for shared packages:

{  "peerDependencies": {    "react": "^18.0.0"  }}

4. Rollup Build is Extremely Slow

Rollup takes too long to build even for small projects.

Root Causes:

• Too many plugins running unnecessary transformations.
• Large dependencies being processed incorrectly.
• Missing cache configurations for incremental builds.

Solution:

Enable caching in Rollup:

import { createCache } from "rollup-plugin-cache";export default {  cache: createCache(),  input: "src/index.js",  output: { file: "dist/bundle.js", format: "esm" }};

Limit unnecessary plugin execution by configuring filters:

babel({  exclude: "node_modules/**"})

Use incremental builds with Rollup watch mode:

rollup --watch

5. Issues with Rollup and CommonJS Modules

Rollup does not properly handle CommonJS modules, causing runtime errors.

Root Causes:

• Modules using require() instead of import.
• Rollup not configured to process CommonJS correctly.
• Missing @rollup/plugin-commonjs plugin.

Solution:

Ensure @rollup/plugin-commonjs is installed:

npm install --save-dev @rollup/plugin-commonjs

Add CommonJS support in rollup.config.js:

import commonjs from "@rollup/plugin-commonjs";export default {  input: "src/index.js",  output: { file: "dist/bundle.js", format: "esm" },  plugins: [commonjs()]};

Best Practices for Rollup Usage

• Use the appropriate plugins for TypeScript, JSX, or non-JS assets.
• Mark dependencies as external when bundling libraries.
• Enable tree-shaking by using ES modules and proper sideEffects configuration.
• Use Rollup caching and watch mode for faster development builds.
• Optimize CommonJS imports with @rollup/plugin-commonjs.

Conclusion

By troubleshooting build failures, tree-shaking inefficiencies, external dependency misconfigurations, and performance bottlenecks, developers can optimize their Rollup builds. Implementing best practices ensures fast, lightweight, and efficient JavaScript bundles.

FAQs

1. Why is Rollup failing with an "Unexpected token" error?

Ensure the appropriate plugins for JSX, TypeScript, or non-JS assets are installed and configured correctly.

2. How do I enable proper tree-shaking in Rollup?

Use ES modules, avoid unnecessary CommonJS imports, and set sideEffects to false in package.json.

3. Why is Rollup bundling external dependencies?

Explicitly mark dependencies as external in rollup.config.js and use peer dependencies where applicable.

4. How do I speed up Rollup builds?

Enable caching, limit unnecessary plugin execution, and use Rollup watch mode for incremental builds.

5. How can I fix issues with CommonJS modules in Rollup?

Install and configure @rollup/plugin-commonjs to properly handle CommonJS imports.