esbuild-plugin-manifest

esbuild-plugin-manifest

This plugin will generate a manifest.json file, mapping original asset names to their corresponding output name.

Install

npm install --save-dev esbuild esbuild-plugin-manifest

Usage

Create file build.js:

const esbuild = require('esbuild');
const manifestPlugin = require('esbuild-plugin-manifest')

esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    outdir: 'output/',
    plugins: [manifestPlugin()],
}).catch((e) => console.error(e.message))

This will generate a manifest.json in the output directory with a mapping of all the unhashed filenames to their corresponding hashed output filename:

{
  "output/index.js": "output/index-4QTUNIID.js"
}

Options

options.hash

Type: Boolean

Default: true

By default we assume that you want to hash the output files. We use [dir]/[name]-[hash] as the default hash format. You can disable hashing by setting this to false or you can set your own hash format by directly using esbuild's entryNames option.

options.shortNames

Type: Boolean | 'input' | 'output'

Default: false

By default we will use the full input and output paths {"output/index.js":"output/index-4QTUNIID.js"}, but when this option is enabled it will use the basename of the files {"index.js":"index-4QTUNIID.js"}

options.extensionless

Type: Boolean | 'input' | 'output'

Default: false

We'll keep all file extensions by default, but you can specify true to remove them from both or one of 'input' or 'output' to only remove them from the input or output respectively. Eg: specifying manifestPlugin({ extensionless: 'input' }) will result in {"output/index":"output/index-4QTUNIID.js"}

options.filename

Type: String

Default: manifest.json

The name of the generated manifest file in the output directory.

options.generate

Type: Function

Default: undefined

A custom Function to create the manifest. The passed function should match the signature of (entries: {[key: string]: string}) => Object; and can return anything as long as it's serialisable by JSON.stringify.

options.filter

Type: Function

Default: undefined

Allows filtering the files which make up the manifest. The passed function should match the signature of (filename: string) => boolean. Return true to keep the file, false to remove the file.

options.useEntrypointKeys

Type: Boolean

Default: false

By default, we use the same extension of the output file as the keys of the manifest key entry. Use this option if you'd rather use the input file (entrypoint) as the manifest key instead.

options.append

Type: Boolean

Default: false

By default, we will overwrite the manifest file if it already exists. This option will append to the existing manifest file instead and only overwrite the entries that have changed.

Advanced Usage Examples

Typescript Entrypoint

// build.js
const esbuild = require('esbuild');
const manifestPlugin = require('esbuild-plugin-manifest')

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'output/',
  plugins: [manifestPlugin()],
}).catch((e) => console.error(e.message))

// manifest.json
{
  "output/index.js": "output/index-4QTUNIID.js"
}

Entrypoint Keys (.ts file example)

// build.js
const esbuild = require('esbuild');
const manifestPlugin = require('esbuild-plugin-manifest')

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'output/',
  plugins: [manifestPlugin({useEntrypointKeys: true})],
}).catch((e) => console.error(e.message))

// manifest.json
{
  "src/index.ts": "output/index-4QTUNIID.js"
}

Multiple Formats

To generate multiple files from the same entrypoint with esbuild, you need to run it multiple times. Utilize esbuilds outExtension option along with our append option to generate multiple files from the same entrypoint.

// build.js
import * as esbuild from 'esbuild'
import manifestPlugin from 'esbuild-plugin-manifest'

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'output/',
  format: 'cjs',
  plugins: [manifestPlugin()],
}).catch((e) => console.error(e.message))

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'output/',
  format: 'esm',
  outExtension: { '.js': '.mjs' },
  plugins: [manifestPlugin({ append: true })],
}).catch((e) => console.error(e.message))

// manifest.json
{
  "output/index.js": "output/index-4QTUNIID.js",
  "output/index.mjs": "output/index-5RUVOJJE.mjs"
}

Changelog

1.0.5 (2024-10-14)

Bug Fixes

• Fix issues when using the append option while watching multiple builds (d621b08), closes #28