rollup-plugin-add-banner

A Rollup plugin that adds banner comments to the output bundle.

简体中文 | Docs

Features

• Template Variables: Auto-resolve ${name}, ${version}, ${author}, ${license} from package.json
• Custom Variables: Define your own template variables
• Multiple Banners: Different banners for different file types (.js, .css, .mjs, etc.)
• Include/Exclude: Fine-grained control with glob patterns
• File Support: Read banner from external file
• Conditional: Environment-based banner control
• SourceMap: Full source map support
• Plugin API: Access banner info at runtime

Installation

# pnpm
pnpm add -D rollup-plugin-add-banner

# npm
npm install -D rollup-plugin-add-banner

Usage

import addBanner from 'rollup-plugin-add-banner'

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/index.js',
    format: 'es'
  },
  plugins: [
    addBanner({
      content: '/*! ${name} v${version} (c) ${author} */'
    })
  ]
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | content | string | '' | Banner content (supports template variables) | | file | string | - | Path to file containing banner (overrides content) | | vars | object | {} | Custom template variables | | include | string \| string[] | - | Files to include (glob patterns) | | exclude | string \| string[] | [] | Files to exclude (glob patterns) | | banners | object | - | Multiple banners by file type | | envVar | string | - | Environment variable for conditional banner | | envValue | string | 'true' | Expected value for env var | | pkgPath | string | 'package.json' | Custom package.json path |

Template Variables

The following variables are automatically resolved from package.json:

| Variable | Description | |----------|-------------| | ${name} | Package name | | ${version} | Package version | | ${author} | Package author | | ${license} | Package license |

You can also define custom variables:

addBanner({
  content: '/*! ${name} v${version} - ${year} */',
  vars: { year: '2024' }
})

Examples

Basic Usage

addBanner({
  content: '/*! ${name} v${version} (c) ${author} */'
})
// Output: /*! rollup-plugin-add-banner v2.0.1 (c) saqqdy */

Multi-line Banner

addBanner({
  content: `
/*!
 * ${name} v${version}
 * (c) ${author}
 * Released under the ${license} License.
 */`
})

Banner from File

addBanner({
  file: './banner.txt'
})

Multiple Banners for Different File Types

addBanner({
  banners: {
    '.js': '/*! ${name} v${version} */',
    '.mjs': '/*! ${name} v${version} - ESM */',
    '.css': '/* ${name} v${version} */'
  }
})

Include/Exclude Patterns

addBanner({
  content: '/*! ${name} */',
  include: ['**/*.js', '**/*.mjs'],  // Only .js and .mjs files
  exclude: ['**/*.min.js']           // Exclude minified files
})

Supported pattern types:

• **/*.js - Extension match
• src/** - Prefix match
• **/dist/** - Directory match
• *.min.js - Wildcard match

Conditional Banner (Environment-based)

Only add banner in production:

addBanner({
  content: '/*! ${name} v${version} */',
  envVar: 'NODE_ENV',
  envValue: 'production'
})

Custom package.json Path

addBanner({
  content: '/*! ${name} v${version} */',
  pkgPath: '../package.json'
})

Plugin API

The plugin exposes an API for runtime access:

const plugin = addBanner({ content: '/* banner */' })

// Get resolved default banner
plugin.api.getBanner() // '/* banner */'

// Get all banners map (if using banners option)
plugin.api.getBanners() // { '.js': '/* ... */' }

// Get all template variables
plugin.api.getVars() // { name: '...', version: '...', ... }

// Check if banner should be added (based on envVar)
plugin.api.shouldAddBanner() // true/false

Integration Examples

With Vite

// vite.config.js
import addBanner from 'rollup-plugin-add-banner'

export default {
  plugins: [
    addBanner({
      content: '/*! ${name} v${version} */'
    })
  ]
}

With Rollup

// rollup.config.js
import addBanner from 'rollup-plugin-add-banner'

export default {
  input: 'src/index.js',
  output: [
    { file: 'dist/index.js', format: 'cjs' },
    { file: 'dist/index.mjs', format: 'es' }
  ],
  plugins: [
    addBanner({
      banners: {
        '.js': '/*! ${name} v${version} - CJS */',
        '.mjs': '/*! ${name} v${version} - ESM */'
      }
    })
  ]
}

Requirements

• Rollup >= 2.0.0
• Node.js >= 12

Migration from v1 to v2

Version 2.0.0 includes breaking changes:

1. Output file paths changed:

   • ESM: dist/index.esm.js → dist/index.mjs
   • CJS: dist/index.js → dist/index.cjs

2. New features available:

   • Template variables (no need to read package.json manually)
   • Include/exclude patterns
   • Multiple banners support
   • Environment-based conditional banners

Before (v1):

import { readFileSync } from 'node:fs'
const pkg = JSON.parse(readFileSync('package.json', 'utf-8'))

addBanner({
  content: `/*! ${pkg.name} v${pkg.version} */`
})

After (v2):

addBanner({
  content: '/*! ${name} v${version} */'
})

Feedback

If you have any questions or suggestions, please open an Issue.

License

MIT