vite-plugin-banner

This article was last updated 3 years 9 months ago, and some content may be legacy. Please use it for reference only.

This is my first Vite plugin. Before I start using Vite, I used rollup for a while, I have used rollup-plugin-banner and rollup-plugin-banner2. But I import them into vite.config.ts and found that them doesn't work. So, I try to learn the plugin development of vite, so there is this work, Its features is similar to WebPack bannerPlugin.

It follows Vite's plugin development specifications, It currently works normally in Vite 2.0, and it can inherit some options of vite.config, e.g. build.outDir.

Features

Adds a banner to the top of each generated chunk.

Install

Install the package from npm (or yarn, or pnpm).

npm install -D vite-plugin-banner

Options

· Type Declarations:

/**
 * Some options from `vite.config.[ts|js]`
 * @tips This options type is supported since `0.2.0`
 */
export interface BannerPluginOptions {
  /**
   * The comment content of the banner
   */
  content: string

  /**
   * The output directory from the configuration of Vite.js
   * @default `dist`
   */
  outDir?: string

  /**
   * Whether to print error messages to the console
   * @tips This option is supported since `0.4.0`
   * @default `false`
   */
  debug?: boolean
}

Usage

In most cases, just use the String format as a plugin option.

In some special cases, such as in VitePress, you might need to use Object format to pass in plugin options, see Optional parameter format.

Basic usage

Add it to vite.config.ts

// vite.config.ts
import banner from 'vite-plugin-banner'
// Other dependencies...

export default defineConfig({
  plugins: [banner('This is the banner content.')],
})

When you run npm run build on your project, In the dist folder(Or the build.outDir in vite.config.ts you configured), Except for vendor files, all js and css files will add a banner to the top.

e.g. in app.b3a7772e.js:

/* This is the banner content. */
var e=Object.assign;import{M as t,d as a,u as r,c......

Advanced usage

Of course, the most ideal banner is related to your package information.

First, You need to update your package.json like this, For example, it contains such field content:

{
  "name": "chengpeiquan.com",
  "version": "0.1.0",
  "description": "My personal website, technology stack based on Vue.js 3.0, and Vite 2.0, use Server Side Generation.",
  "author": "chengpeiquan",
  "homepage": "https://chengpeiquan.com/"
}

Then, import the package.json into vite.config.ts, update the banner like this:

// vite.config.ts
import pkg from './package.json'
// Other dependencies...

export default defineConfig({
  plugins: [
    banner(
      `/**\n * name: ${pkg.name}\n * version: v${pkg.version}\n * description: ${pkg.description}\n * author: ${pkg.author}\n * homepage: ${pkg.homepage}\n */`,
    ),
  ],
})

Run npm run build, you can see the banner become more detailed.

e.g. in app.6936be52.js:

/**
 * name: chengpeiquan.com
 * version: v0.1.0
 * description: My personal website, technology stack based on Vue.js 3.0, and Vite 2.0, use Server Side Generation.
 * author: chengpeiquan
 * homepage: https://chengpeiquan.com/
 */
var e=Object.assign;import{M as t,d as a,u as r,c......

Fun usage

If you want to make some banners that show your personality, you can make some interesting content from some online generators.

Such as:

• http://www.network-science.de/ascii/

• https://www.bootschool.net/ascii

// vite.config.ts
export default defineConfig({
  plugins: [
    banner(`
    ██   ██         ███████   ██      ██ ████████   ██    ██   ███████   ██     ██
    ░██  ░██        ██░░░░░██ ░██     ░██░██░░░░░   ░░██  ██   ██░░░░░██ ░██    ░██
    ░██  ░██       ██     ░░██░██     ░██░██         ░░████   ██     ░░██░██    ░██
    ░██  ░██      ░██      ░██░░██    ██ ░███████     ░░██   ░██      ░██░██    ░██
    ░██  ░██      ░██      ░██ ░░██  ██  ░██░░░░       ░██   ░██      ░██░██    ░██
    ░██  ░██      ░░██     ██   ░░████   ░██           ░██   ░░██     ██ ░██    ░██
    ░██  ░████████ ░░███████     ░░██    ░████████     ░██    ░░███████  ░░███████ 
    ░░   ░░░░░░░░   ░░░░░░░       ░░     ░░░░░░░░      ░░      ░░░░░░░    ░░░░░░░  
    `),
  ],
})

Run npm run build, e.g. in app.d9a287b8.js:

/*
    ██   ██         ███████   ██      ██ ████████   ██    ██   ███████   ██     ██
    ░██  ░██        ██░░░░░██ ░██     ░██░██░░░░░   ░░██  ██   ██░░░░░██ ░██    ░██
    ░██  ░██       ██     ░░██░██     ░██░██         ░░████   ██     ░░██░██    ░██
    ░██  ░██      ░██      ░██░░██    ██ ░███████     ░░██   ░██      ░██░██    ░██
    ░██  ░██      ░██      ░██ ░░██  ██  ░██░░░░       ░██   ░██      ░██░██    ░██
    ░██  ░██      ░░██     ██   ░░████   ░██           ░██   ░░██     ██ ░██    ░██
    ░██  ░████████ ░░███████     ░░██    ░████████     ░██    ░░███████  ░░███████
    ░░   ░░░░░░░░   ░░░░░░░       ░░     ░░░░░░░░      ░░      ░░░░░░░    ░░░░░░░
     */
var e=Object.assign;import{M as t,d as a,u as r,c......

Optional parameter format

I'm not sure what other scenarios besides VitePress need to use this method to pass in options, so I use VitePress as an example, I hope it can give you a reference.

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'
import banner from 'vite-plugin-banner'
import pkg from '../../package.json'

const outDir = '../dist'

export default defineConfig({
  // Specify the output directory for packaging
  outDir,

  // Use Vite plugins
  vite: {
    plugins: [
      // Please remember to use the options in Object format here
      banner({
        outDir,
        content: `/**\n * name: ${pkg.name}\n * version: v${pkg.version}\n * description: ${pkg.description}\n * author: ${pkg.author}\n * homepage: ${pkg.homepage}\n */`,
      }),
    ],
  },
  // ...
})

Why do it?

Because in VitePress, what you get through viteConfig.build.outDir is always a .temp temporary directory, not the final output directory, so you need to manually specify the output directory to inform the plugin.

Of course, with the updated version of Vitepress, this is not necessarily required, but you can choose to do so when you need it.