esbuild-manifest-plugin

1.0.0 verified Fri May 01 auth: no javascript

An esbuild plugin (v1.0.0, released 2024) that generates a manifest.json mapping input filenames to their output filenames after digestion with content hashes or directory nesting. It automatically enables esbuild's metafile option and optionally rewrites node_modules asset paths for convenience. Unlike general asset plugins, it specifically targets bundlers needing a Rails-like manifest for cache busting or server-side filename resolution. Updated infrequently, with a focus on simplicity and interoperability with esbuild-sass-plugin.

Common errors

error Error: Cannot find module 'esbuild-manifest-plugin' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install -D esbuild-manifest-plugin' to install it.

error TypeError: manifestPlugin is not a function ↓

cause Incorrect import: using default import from CommonJS module.

fix

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

error Error: The plugin "esbuild-manifest-plugin" requires the "metafile" option ↓

cause If user explicitly set metafile: false, plugin reports error (though code says it auto-enables). Actually the plugin always forces metafile true, but if esbuild refuses, this may appear.

fix

Remove 'metafile: false' from your esbuild config.

error Error: Build failed with 1 error: error: [plugin: esbuild-manifest-plugin] Manifest generation failed ↓

cause Internal error in plugin, possibly due to missing outdir or write permissions.

fix

Ensure outdir exists and is writable. Check esbuild logs for preceding errors.

Warnings

gotcha The plugin automatically enables the 'metafile' option in esbuild if not already set. This may cause unexpected metafile output size for large builds. ↓

fix Ensure your build has enough memory or explicitly disable metafile if you don't need it (but then the plugin will enable it anyway).

gotcha nodeModulesPrefix default is empty string, which rewrites node_modules paths to be relative without prefix (e.g., 'example-lib/image.png'). This may collide with your own asset paths if you have files with the same names. ↓

fix Set nodeModulesPrefix to '~' or false to avoid collisions. Review generated manifest for duplicates.

deprecated No deprecations yet as plugin is v1.0.0.

breaking No breaking changes reported yet.

Install

npm install esbuild-manifest-plugin

yarn add esbuild-manifest-plugin

pnpm add esbuild-manifest-plugin

Imports

default

wrong

const manifestPlugin = require('esbuild-manifest-plugin').default

correct

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

Package exports a function directly, not as default export. Use require() as shown.

manifestPlugin
wrong
```
import { default as manifestPlugin } from 'esbuild-manifest-plugin'
```
correct
```
import manifestPlugin from 'esbuild-manifest-plugin'
```
ESM default import works because the package uses module.exports = function. This is the preferred way for ESM projects.
ManifestPluginOptions
wrong
```
import { ManifestPluginOptions } from 'esbuild-manifest-plugin'
```
correct
```
type ManifestPluginOptions = Parameters<typeof manifestPlugin>[0]
```
No types are exported. Infer types or define manually. The plugin is JavaScript-only without TypeScript definitions.

Quickstart

Build an entry point and generate a manifest.json with content-hashed filenames. The plugin automatically enables metafile.

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

esbuild.build({
  entryPoints: ['application.js'],
  entryNames: '[dir]/[name]-[hash]',
  assetNames: '[dir]/[name]-[hash]',
  bundle: true,
  outdir: path.join(__dirname, 'public/assets'),
  plugins: [manifestPlugin()]
}).then(() => {
  console.log('Build complete. Manifest written to outdir.');
}).catch(() => process.exit(1));