rollup-plugin-banner2

1.3.1 verified Mon Apr 27 auth: no javascript

Rollup plugin to prepend a banner (e.g., license, metadata) before bundled JavaScript code, surviving minification where Rollup's built-in output.banner is stripped by plugins like rollup-plugin-uglify. Version 1.3.1 (stable; maintained as of 2024). Key differentiators from rollup-plugin-banner (unmaintained): supports sourcemaps, per-chunk banners via ChunkInfo, custom formatters (docBlock, docBlockAndGap), and async resolveBanner. Drawbacks vs alternatives: no file path loading, no package.json template injection, no automatic JS comment wrapping. Requires Node >=12.13 and Rollup.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-banner2/index.js not supported. ↓

cause Using CommonJS require() with ESM-only package.

fix

Use import statement instead of require().

error TypeError: banner2 is not a function ↓

cause Importing with incorrect syntax or using default import for a named export.

fix

Use import banner2 from 'rollup-plugin-banner2' (correct) or const banner2 = (await import('rollup-plugin-banner2')).default.

error Error: The "sourceMap" option is deprecated; use "sourcemap" (all lowercase). ↓

cause Using incorrect camelCase option name.

fix

Change sourceMap to sourcemap in options object.

Warnings

breaking Package is ESM-only since v1.0. Node <12 incompatible; CJS require() fails. ↓

fix Use import syntax. Update Node to >=12.13. If legacy CJS required, use dynamic import() or downgrade to rollup-plugin-banner (CJS).

deprecated The 'formatter' option only supports 'docBlock' and 'docBlockAndGap'; custom formatters were removed in a prior version. ↓

fix Use resolveBanner function to implement custom formatting.

gotcha resolveBanner must return a string, stringifiable object, or falsey. Returning undefined or null results in empty banner. ↓

fix Ensure function always returns something (string, Buffer, etc.) or handle falsey explicitly.

gotcha When sourcemaps are enabled (default), banner content is added to sourcemaps; minifiers may still strip banner if not sourcemap-aware. ↓

fix If banner is stripped by minifier, try disabling sourcemaps (sourcemap: false) or use a dedicated banner plugin designed for minifiers.

Install

npm install rollup-plugin-banner2

yarn add rollup-plugin-banner2

pnpm add rollup-plugin-banner2

Imports

banner2

wrong

const banner2 = require('rollup-plugin-banner2')

correct

import banner2 from 'rollup-plugin-banner2'

Package is ESM-only; CJS require will fail with ERR_REQUIRE_ESM in Node >=12.

banner2

wrong

export default { plugins: [banner2('/* my banner */')] }

correct

export default { plugins: [banner2(() => '/* my banner */')] }

resolveBanner must be a function, not a string literal.

BannerFunction

wrong

import { BannerFunction } from 'rollup-plugin-banner2'

correct

import type { BannerFunction } from 'rollup-plugin-banner2'

Type-only import; runtime import will throw TypeError.

Quickstart

Basic Rollup config using banner2 with per-chunk banners and docBlock formatter.

import banner2 from 'rollup-plugin-banner2';

export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'es' },
  plugins: [
    banner2(
      (chunk) => `/**
 * Bundle: ${chunk.fileName}
 */
`,
      { formatter: 'docBlock' }
    )
  ]
};