esbuild Metadata Report

1.0.3 verified Fri May 01 auth: no javascript

A tool to generate an HTML report from esbuild's metafile output, visualizing bundle metadata such as file sizes, dependencies, and timings. Version 1.0.3, stable. Designed for esbuild, it works as a plugin or standalone function. Differentiable by its interactive, self-contained HTML report that aids debugging and optimization of esbuild builds. Supports CommonJS only.

Common errors

error Error: Cannot find module 'esbuild-metadata-report' ↓

cause Package not installed or missing from node_modules.

fix

npm install esbuild-metadata-report

error TypeError: metadataReport is not a function ↓

cause Using ES import syntax (import) when package is CJS-only.

fix

Use const metadataReport = require('esbuild-metadata-report')

error Error: metafile is required if using as a function ↓

cause Using function form without passing metafile property.

fix

Pass metafile: result.metafile in options object.

Warnings

gotcha Package does not provide TypeScript types despite having 'Ships TypeScript types: yes' in metadata. Actual types are missing. ↓

fix Install @types/esbuild-metadata-report if available, or create custom declarations.

gotcha The plugin requires metafile: true in esbuild options; otherwise, the report will be empty or error. ↓

fix Ensure metafile: true is set in esbuild.build options.

deprecated Version 1.0.3 uses require; no ESM support. Future versions may drop CJS. ↓

fix Use dynamic import() in ESM projects if needed, but prefer require for now.

Install

npm install esbuild-metadata-report

yarn add esbuild-metadata-report

pnpm add esbuild-metadata-report

Imports

metadataReport

wrong

import metadataReport from 'esbuild-metadata-report'

correct

const metadataReport = require('esbuild-metadata-report')

This package is CJS-only; ES import will fail.

metadataReport

const metadataReport = require('esbuild-metadata-report')

Default export is the function/plugin factory.

metadataReport

wrong

import { metadataReport } from 'esbuild-metadata-report'

correct

const metadataReport = require('esbuild-metadata-report')

Named export not available; the package exports a single default function.

Quickstart

Demonstrates using esbuild-metadata-report as an esbuild plugin to generate an HTML report from the build metafile.

const esbuild = require('esbuild');
const metadataReport = require('esbuild-metadata-report');

esbuild.build({
  entryPoints: ['app.js'],
  bundle: true,
  outfile: 'out.js',
  metafile: true,
  plugins: [
    metadataReport({
      name: 'My Report',
      outputFile: 'report.html'
    })
  ]
}).catch(() => process.exit(1));