{"id":14939,"library":"steal-rollup","title":"Rollup.js Module Bundler","description":"Rollup is a highly optimized JavaScript module bundler that compiles small pieces of code into larger, more complex libraries or applications. It primarily leverages the standardized ES module format (ESM) for code, enabling advanced optimizations like tree-shaking to produce exceptionally small and efficient bundles. Rollup's current stable version is `4.60.2`, with frequent minor and patch releases (often weekly or bi-weekly) addressing bugs and adding features, while major versions introduce significant changes. Unlike bundlers focused on web applications, Rollup excels at bundling libraries and frameworks, offering a lean core with a powerful, flexible plugin API to handle various build scenarios, including CommonJS, AMD, UMD, and ES module outputs for different environments.","status":"active","version":"0.58.4","language":"javascript","source_language":"en","source_url":"https://github.com/rollup/rollup","tags":["javascript","modules","bundler","bundling","es6","optimizer","typescript"],"install":[{"cmd":"npm install steal-rollup","lang":"bash","label":"npm"},{"cmd":"yarn add steal-rollup","lang":"bash","label":"yarn"},{"cmd":"pnpm add steal-rollup","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For programmatic use, `rollup` is an async function that takes `InputOptions`. Configuration files (`rollup.config.js` or `.mjs`) can use `export default` for ESM-style config. Rollup 4 requires Node.js 18.0.0+ for its native binary, or `@rollup/wasm-node` as a fallback.","wrong":"const rollup = require('rollup');","symbol":"rollup","correct":"import { rollup } from 'rollup';"},{"note":"This is a TypeScript type definition, used for type-checking when defining Rollup's input configuration. It should be imported using `import type` to avoid bundling issues.","wrong":"import { InputOptions } from 'rollup';","symbol":"InputOptions","correct":"import type { InputOptions } from 'rollup';"},{"note":"This is a TypeScript type definition for Rollup's output configuration. Use `import type` for proper type-only imports.","wrong":"import { OutputOptions } from 'rollup';","symbol":"OutputOptions","correct":"import type { OutputOptions } from 'rollup';"},{"note":"When developing custom Rollup plugins with TypeScript, `Plugin` is a critical interface for type safety. Use `import type`.","wrong":"import { Plugin } from 'rollup';","symbol":"Plugin","correct":"import type { Plugin } from 'rollup';"}],"quickstart":{"code":"import { rollup } from 'rollup';\nimport type { InputOptions, OutputOptions, RollupBuild } from 'rollup';\nimport commonjs from '@rollup/plugin-commonjs';\nimport resolve from '@rollup/plugin-node-resolve';\n\nasync function buildBundle() {\n  // Define input options for your Rollup build\n  const inputOptions: InputOptions = {\n    input: 'src/main.js', // Your application's entry point\n    plugins: [\n      resolve(), // Locates modules using Node.js resolution algorithm\n      commonjs(), // Converts CommonJS modules to ES6, so they can be bundled by Rollup\n      // Add other plugins like @rollup/plugin-typescript, @rollup/plugin-babel here\n    ],\n  };\n\n  // Define output options for the generated bundle\n  const outputOptions: OutputOptions = {\n    file: 'dist/bundle.js',\n    format: 'es', // Output format: 'es' (ES Modules), 'cjs' (CommonJS), 'umd', 'iife', etc.\n    sourcemap: true, // Generate sourcemaps for debugging\n    name: 'myLibrary', // Required for IIFE/UMD formats\n  };\n\n  let bundle: RollupBuild | undefined;\n  try {\n    // 1. Call rollup to create a bundle\n    bundle = await rollup(inputOptions);\n\n    // 2. Generate and write the output file(s)\n    await bundle.write(outputOptions);\n\n    console.log('Rollup build completed successfully!');\n  } catch (error) {\n    console.error('Rollup build failed:', error);\n    process.exit(1);\n  } finally {\n    // 3. Close the bundle to release resources (e.g., file watchers)\n    if (bundle) {\n      await bundle.close();\n    }\n  }\n}\n\n// Example entry file (src/main.js):\n// export const greet = (name) => `Hello, ${name}!`;\n// console.log(greet('World'));\n\nbuildBundle();","lang":"typescript","description":"This quickstart demonstrates how to programmatically use Rollup with its JavaScript API to bundle a project, including common plugins for module resolution and CommonJS conversion, and outputs to an ES module format with sourcemaps."},"warnings":[{"fix":"Ensure your Node.js environment is 18.0.0 or higher. Update Rollup plugins to their latest compatible versions. Adjust plugin `transform` and `load` hooks to explicitly return `undefined` if they aren't processing a module. Review your `InputOptions` for `moduleSideEffects` if your bundle relies on side effects. Update plugin API usage as per Rollup 4 migration guide, particularly `this.resolve` default `skipSelf: true` for plugin authors.","message":"Rollup v4.0.0 introduced several breaking changes, including an increase in the minimal required Node.js version to 18.0.0 and a change in the default `moduleSideEffects` to `false` for packages. Plugins must now return `undefined` from `transform` or `load` hooks when they don't want to handle a module, instead of `null`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refactor custom plugins to avoid returning import attributes from `load` or `transform` hooks. Use `this.addWatchFile()` within plugin `load` hooks for virtual files to ensure they are watched.","message":"Returning import attributes from `load` or `transform` plugin hooks is deprecated in Rollup 4.57.0 and will no longer be supported in Rollup 5.","severity":"deprecated","affected_versions":">=4.57.0"},{"fix":"Install `@rollup/plugin-commonjs` and `@rollup/plugin-node-resolve` from npm, and add them to your `rollup.config.js` or programmatic input options. For example: `plugins: [resolve(), commonjs()]`.","message":"Rollup's core focuses on ES modules. To handle CommonJS modules or resolve Node.js-style bare module imports, you typically need to install and configure `@rollup/plugin-commonjs` and `@rollup/plugin-node-resolve` respectively. Without them, Rollup cannot correctly bundle many npm packages.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If your Rollup configuration produces multiple output chunks (e.g., due to multiple inputs or dynamic imports), ensure `output.dir` is used to specify an output directory, rather than `output.file`. For single-file bundles, `output.file` is appropriate.","message":"When bundling multiple entry points or using code-splitting, `output.dir` must be specified as an output directory, not `output.file`. Attempting to use `output.file` with multiple outputs will result in an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `\"moduleResolution\": \"bundler\"` (or `'node16'`, `'nodenext'`) in your `tsconfig.json`'s `compilerOptions`. Alternatively, `\"skipLibCheck\": true` might resolve certain type issues, but is less precise. Also ensure all source files are included in `tsconfig.json`'s `include` array.","message":"TypeScript users may encounter issues with module resolution or `default` exports if `moduleResolution` is not configured correctly in `tsconfig.json`. Rollup 4 expects `moduleResolution: 'bundler'` (or `node16`/`nodenext`).","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If the module is CommonJS, you might need to use `import * as name from 'module'` or ensure `@rollup/plugin-commonjs` is configured correctly and placed *after* `@rollup/plugin-node-resolve` in your plugin list. If it's an ESM module, verify the named export exists.","cause":"This typically means an `import { namedExport } from 'module'` statement refers to an export that doesn't exist in the imported module, often happening with CommonJS modules that only have a default export.","error":"Error: \"[name]\" is not exported by \"[module]\""},{"fix":"Change your Rollup configuration to use `output.dir: 'dist'` (or your desired output directory) instead of `output.file: 'bundle.js'` when your build process generates more than one output chunk.","cause":"You are attempting to output multiple JavaScript files (e.g., from multiple entry points or code-splitting) but have specified a single file path using `output.file` instead of a directory using `output.dir`.","error":"Error: When building multiple chunks, the output.dir option must be used, not output.file."},{"fix":"Rename your configuration file to `rollup.config.mjs` to explicitly tell Node.js to treat it as an ES module, or add `\"type\": \"module\"` to your `package.json` file.","cause":"Your `rollup.config.js` file uses ES module syntax (like `import` and `export default`) but Node.js is trying to load it as a CommonJS module.","error":"Error: Node tried to load your configuration file as CommonJS even though it is likely an ES module."},{"fix":"Verify that all `.ts` and `.tsx` files intended for bundling are correctly listed in the `include` array within your `tsconfig.json`. Also, ensure that the `@rollup/plugin-typescript` (or equivalent) is properly configured in your Rollup setup.","cause":"This error often occurs in TypeScript projects when a file is imported or specified as an entry point, but it's not correctly included in the `tsconfig.json`'s `include` array, or the `@rollup/plugin-typescript` isn't configured to find it.","error":"Error: Could not find sourceFile: '[path/to/file.ts]'"}],"ecosystem":"npm"}