Rollup.js Module Bundler

Common errors

• Error: "[name]" is not exported by "[module]"

  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.
  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.

• Error: When building multiple chunks, the output.dir option must be used, not output.file.

  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`.
  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.

• Error: Node tried to load your configuration file as CommonJS even though it is likely an ES module.

  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.
  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.

• Error: Could not find sourceFile: '[path/to/file.ts]'

  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.
  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.

Warnings

• breaking 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`.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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()]`.
• gotcha 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.
  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.
• gotcha 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`).
  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.

Install

• npm install steal-rollup npm
• yarn add steal-rollup yarn
• pnpm add steal-rollup pnpm

Imports

• rollup
  wrong:

  const rollup = require('rollup');

  correct:

  import { rollup } from 'rollup';

  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.
• InputOptions
  wrong:

  import { InputOptions } from 'rollup';

  correct:

  import type { InputOptions } from 'rollup';

  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.
• OutputOptions
  wrong:

  import { OutputOptions } from 'rollup';

  correct:

  import type { OutputOptions } from 'rollup';

  This is a TypeScript type definition for Rollup's output configuration. Use `import type` for proper type-only imports.
• Plugin
  wrong:

  import { Plugin } from 'rollup';

  correct:

  import type { Plugin } from 'rollup';

  When developing custom Rollup plugins with TypeScript, `Plugin` is a critical interface for type safety. Use `import type`.

Quickstart

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.

import { rollup } from 'rollup';
import type { InputOptions, OutputOptions, RollupBuild } from 'rollup';
import commonjs from '@rollup/plugin-commonjs';
import resolve from '@rollup/plugin-node-resolve';

async function buildBundle() {
  // Define input options for your Rollup build
  const inputOptions: InputOptions = {
    input: 'src/main.js', // Your application's entry point
    plugins: [
      resolve(), // Locates modules using Node.js resolution algorithm
      commonjs(), // Converts CommonJS modules to ES6, so they can be bundled by Rollup
      // Add other plugins like @rollup/plugin-typescript, @rollup/plugin-babel here
    ],
  };

  // Define output options for the generated bundle
  const outputOptions: OutputOptions = {
    file: 'dist/bundle.js',
    format: 'es', // Output format: 'es' (ES Modules), 'cjs' (CommonJS), 'umd', 'iife', etc.
    sourcemap: true, // Generate sourcemaps for debugging
    name: 'myLibrary', // Required for IIFE/UMD formats
  };

  let bundle: RollupBuild | undefined;
  try {
    // 1. Call rollup to create a bundle
    bundle = await rollup(inputOptions);

    // 2. Generate and write the output file(s)
    await bundle.write(outputOptions);

    console.log('Rollup build completed successfully!');
  } catch (error) {
    console.error('Rollup build failed:', error);
    process.exit(1);
  } finally {
    // 3. Close the bundle to release resources (e.g., file watchers)
    if (bundle) {
      await bundle.close();
    }
  }
}

// Example entry file (src/main.js):
// export const greet = (name) => `Hello, ${name}!`;
// console.log(greet('World'));

buildBundle();