vite-plugin-banner

KO | EN

gitlite — search

#php #java #python #ruby #javascript #hacktoberfest #nodejs #shell #raspberry-pi #jquery #wordpress #library

vite-plugin-banner

★ 113 Open GitHub ↗

A banner plugin for Vite. It can adds a banner to the top of each generated chunk.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

English | [简体中文](https://github.com/chengpeiquan/vite-plugin-banner/blob/main/README.zh-CN.md)

## Features

Adds a banner to the top of each generated chunk.

## Installation

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

```bash
npm install -D vite-plugin-banner
```

## Options

· Type Declarations:

````ts
/**
 * Some options from `vite.config.[ts|js]`
 * @since 0.2.0
 */
export interface BannerPluginOptions {
  /**
   * The comment content of the banner
   *
   * @since ^0.6.0 support for `ContentCallback` types
   */
  content: string | ContentCallback

/**
   * The output directory from the configuration of Vite.js
   *
   * @see https://vitejs.dev/config/build-options.html#build-outdir
   *
   * @default viteConfig.build.outDir
   */
  outDir?: string

/**
   * Whether to print error messages to the console
   *
   * @since 0.4.0
   *
   * @default false
   */
  debug?: boolean

/**
   * By default, the validity of the content will be verified.
   *
   * If set to `false`, no verification will be performed.
   *
   * @see https://github.com/chengpeiquan/vite-plugin-banner/issues/13
   *
   * @since 0.5.0
   *
   * @default true
   */
  verify?: boolean
}

/**
 * Callback function to get the contents to be injected.(or not inject)
 *
 * @since 0.6.0
 *
 * @param fileName - The name of the file currently being processed
 *
 * @returns
 *  1. When a valid string is returned, it will become the banner content
 *  2. Returning a Falsy value will skip processing(e.g. `''`, `null`, `undefined`)
 *
 * @example
 *
 * ```ts
 *  content: (fileName: string) => {
 *    // Or use switch statement
 *    return fileName.endsWith('.js')
 *      ? 'This message will inject into `js` files.'
 *      : 'This message will inject into other files.'
 *  }
 * ```
 */
export type ContentCallback = (fileName: string) => string | null | undefined
````

## Usage

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

### Basic usage

Add it to `vite.config.ts`

```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](https://vitejs.dev/config/#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`:

```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:

```json
{
  "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:

```ts
// 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`:

```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/](http://www.network-science.de/ascii/)

- [https://www.bootschool.net/ascii](https://www.bootschool.net/ascii)

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

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

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

### Add different banners

Since `0.6.0`, it supports incoming function callback to set the content of Banner. When using `ContentCallback` type, this plugin will judge what content should be added according to the internal logic of the function.

1. When a valid string is returned, it will become the banner content
2. Returning a [Falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) value will skip processing(e.g. `''`, `null`, `undefined`)

e.g.

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

export default defineConfig({
  plugins: [
    banner((fileName: string) => {
      // Or use switch statement
      return fileName.endsWith('.js')
        ? 'This message will inject into `js` files.'
        : 'This message will inject into other files.'
    }),
  ],
})
```

### Optional parameter format

Sometimes plugins can't get `outDir` successfully (for example, in VitePress, the plugin 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.

Take VitePress as an example:

```ts
// 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 */`,
      }),
    ],
  },
  // ...
})
```

In addition to `outDir`, you can also use `debug`, `verify` and other options, see the above [Options](#options) description for details.

## License

vite-plugin-banner

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README