vite-plugin-banner

0.8.1 verified Mon Apr 27 auth: no javascript

A Vite plugin that adds a banner comment to the top of each generated chunk (JS and CSS files). Current stable version is 0.8.1, compatible with Vite 6. Released under active maintenance with monthly updates. Key differentiators: lightweight (no extra dependencies), supports string or callback-based banner content, allows debug mode and content verification toggle. Compared to alternatives like rollup-plugin-banner, it is Vite-native and supports ESM/CJS.

Common errors

error Error: The plugin 'vite-plugin-banner' doesn't have a default export ↓

cause Using require('vite-plugin-banner') in a CommonJS context (Vite config using CJS).

fix

Switch to ESM: use import banner from 'vite-plugin-banner' and ensure vite.config.ts is processed as ESM.

error TypeError: content is not a function ↓

cause Passed an object without content property or invalid ContentCallback.

fix

Use correct options format: { content: '...' } or { content: (fileName) => '...' }.

error BannerPluginError: The banner content is invalid, please check it. ↓

cause verify option is true and content contains invalid comment characters like '/*' or '*/'.

fix

Set verify: false or sanitize content to avoid nested comment tokens.

Warnings

breaking v0.8.0: Removed default outDir value; plugin now uses Vite's build.outDir. Previously a hardcoded default could conflict. ↓

fix Ensure your Vite config has build.outDir set, or manually pass outDir option to plugin.

gotcha Callback content returning falsy values (e.g., '') was not properly skipped until v0.7.1; could cause empty banner or errors. ↓

fix Upgrade to v0.7.1+ or ensure callback always returns a non-empty string or null.

gotcha verify option defaults to true; if content contains characters that could break JavaScript comments (e.g., */), plugin may reject it. ↓

fix Set verify: false to skip content validation, or avoid problematic characters.

deprecated v0.3.0: Dropped CJS require() support; after v0.3.0 only ESM import works. ↓

fix Use import banner from 'vite-plugin-banner' instead of require().

Install

npm install vite-plugin-banner

yarn add vite-plugin-banner

pnpm add vite-plugin-banner

Imports

default

wrong

const banner = require('vite-plugin-banner')

correct

import banner from 'vite-plugin-banner'

Package is ESM-only since v0.3.0; use default import in Vite config.

ContentCallback

wrong

import { ContentCallback } from 'vite-plugin-banner'

correct

import banner, { ContentCallback } from 'vite-plugin-banner'

TypeScript users may import the callback type alongside the default import.

BannerPluginOptions
```
import banner, { BannerPluginOptions } from 'vite-plugin-banner'
```
TypeScript type for options object; exported alongside default.

Quickstart

Basic setup with a callback that adds file-specific banners to JS and CSS chunks.

// vite.config.ts
import { defineConfig } from 'vite'
import banner from 'vite-plugin-banner'

export default defineConfig({
  plugins: [
    banner({
      content: (fileName: string) => {
        if (fileName.endsWith('.js')) {
          return `/*! Bundle: ${fileName} */`
        }
        if (fileName.endsWith('.css')) {
          return `/* Style: ${fileName} */`
        }
        return null
      },
      debug: true,
      verify: true
    })
  ]
})