saqqdy/rollup-plugin-add-banner

README

rollup-plugin-add-banner

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

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:

Output file paths changed:
- ESM: dist/index.esm.js → dist/index.mjs
- CJS: dist/index.js → dist/index.cjs
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