esbuild - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: esbuild for comprehensive documentation.

When NOT to Use This Skill

• Complex applications - Use Vite (which uses esbuild internally)
• Need many plugins - Webpack or Rollup have richer ecosystems
• CSS modules, PostCSS - Vite handles these better
• HMR required - Vite provides full HMR experience

When to Use This Skill

• Ultra-fast simple bundling
• TypeScript library builds
• Understanding how Vite works
• Custom build scripts

Setup

npm install -D esbuild

CLI Usage

# Bundle single file
esbuild src/index.ts --bundle --outfile=dist/bundle.js

# Watch mode
esbuild src/index.ts --bundle --outfile=dist/bundle.js --watch

# Minify for production
esbuild src/index.ts --bundle --minify --outfile=dist/bundle.min.js

# Multiple outputs
esbuild src/index.ts --bundle --outdir=dist --format=esm --format=cjs

# Source maps
esbuild src/index.ts --bundle --sourcemap --outfile=dist/bundle.js

API Usage

// build.ts
import * as esbuild from 'esbuild';

// Simple build
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
});

// Production build
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  outfile: 'dist/bundle.min.js',
});

Configuration Options

await esbuild.build({
  // Entry points
  entryPoints: ['src/index.ts', 'src/worker.ts'],
  // Or object for custom names
  entryPoints: {
    main: 'src/index.ts',
    worker: 'src/worker.ts',
  },

  // Output
  bundle: true,
  outdir: 'dist',
  outfile: 'dist/bundle.js',    // Single file
  outExtension: { '.js': '.mjs' },

  // Format
  format: 'esm',   // 'esm' | 'cjs' | 'iife'
  platform: 'node', // 'browser' | 'node' | 'neutral'
  target: ['es2020', 'chrome90', 'firefox88'],

  // Optimization
  minify: true,
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true,
  treeShaking: true,

  // Source maps
  sourcemap: true,        // External .map file
  sourcemap: 'inline',    // Inline in JS
  sourcemap: 'linked',    // External with reference

  // Splitting (ESM only)
  splitting: true,
  chunkNames: 'chunks/[name]-[hash]',

  // External packages
  external: ['react', 'react-dom'],
  packages: 'external',   // All node_modules external

  // Define
  define: {
    'process.env.NODE_ENV': '"production"',
    '__VERSION__': '"1.0.0"',
  },

  // Loaders
  loader: {
    '.png': 'file',
    '.svg': 'text',
    '.json': 'json',
  },

  // Paths
  alias: {
    '@': './src',
    '@components': './src/components',
  },
  resolveExtensions: ['.tsx', '.ts', '.jsx', '.js'],

  // Banner/Footer
  banner: {
    js: '/* Bundle generated at ' + new Date().toISOString() + ' */',
  },
  footer: {
    js: '/* End of bundle */',
  },

  // Legal comments
  legalComments: 'none', // 'none' | 'inline' | 'eof' | 'linked' | 'external'

  // Metafile for analysis
  metafile: true,
});

Watch Mode (API)

// Watch with rebuild
const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
});

await ctx.watch();
console.log('Watching for changes...');

// Later: stop watching
await ctx.dispose();

Dev Server

const ctx = await esbuild.context({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outdir: 'dist',
});

// Start dev server
await ctx.serve({
  servedir: 'dist',
  port: 3000,
});

console.log('Server running on http://localhost:3000');

Plugins

// Custom plugin structure
const myPlugin: esbuild.Plugin = {
  name: 'my-plugin',
  setup(build) {
    // Resolve hook
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: 'env-ns',
    }));

    // Load hook
    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json',
    }));

    // Start/End hooks
    build.onStart(() => {
      console.log('Build started');
    });

    build.onEnd((result) => {
      console.log(`Build ended with ${result.errors.length} errors`);
    });
  },
};

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  plugins: [myPlugin],
  outfile: 'dist/bundle.js',
});

Common Plugins

// Environment variables plugin
const envPlugin: esbuild.Plugin = {
  name: 'env',
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: 'env-ns',
    }));

    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: `export const API_URL = ${JSON.stringify(process.env.API_URL)}`,
      loader: 'ts',
    }));
  },
};

// CSS modules plugin (basic)
const cssModulesPlugin: esbuild.Plugin = {
  name: 'css-modules',
  setup(build) {
    build.onLoad({ filter: /\.module\.css$/ }, async (args) => {
      const css = await fs.readFile(args.path, 'utf8');
      // Process CSS modules...
      return {
        contents: `export default ${JSON.stringify(classNames)}`,
        loader: 'js',
      };
    });
  },
};

Library Build

// Build library for npm
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  external: ['react', 'react-dom'],  // Peer deps
  outdir: 'dist',
  format: 'esm',
  outExtension: { '.js': '.mjs' },
});

// Also build CJS
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  external: ['react', 'react-dom'],
  outdir: 'dist',
  format: 'cjs',
  outExtension: { '.js': '.cjs' },
});

// package.json for library
{
  "name": "my-lib",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}

Bundle Analysis

const result = await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  metafile: true,
  outfile: 'dist/bundle.js',
});

// Write metafile
await fs.writeFile('meta.json', JSON.stringify(result.metafile));

// Analyze
const analysis = await esbuild.analyzeMetafile(result.metafile);
console.log(analysis);

TypeScript Declaration

// esbuild doesn't generate .d.ts - use tsc
import { execSync } from 'child_process';

// Build JS with esbuild
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/index.js',
});

// Generate types with tsc
execSync('tsc --emitDeclarationOnly --declaration --outDir dist');

Comparison with Other Bundlers

Feature	esbuild	Webpack	Vite	Rollup
Speed	Fastest	Slow	Fast (uses esbuild)	Medium
Config	Simple	Complex	Simple	Medium
Plugins	Limited	Many	Many	Many
HMR	Basic	Full	Full	Plugin
Tree-shaking	Yes	Yes	Yes	Best
Code-splitting	ESM only	Full	Full	Full

When to Use esbuild

Scenario	Recommendation
Simple bundling	esbuild
Library build	esbuild + tsc
Complex app	Vite (uses esbuild)
Legacy support	Webpack
Need plugins	Vite or Rollup

Anti-Patterns to Avoid

• Do not use for complex apps (use Vite)
• Do not expect advanced HMR
• Do not forget tsc for .d.ts
• Do not ignore external for libraries

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Using for complex apps	Missing features	Use Vite for apps, esbuild for libraries
Not externalizing dependencies	Large library bundles	Use external: [...] for peer deps
No .d.ts generation	Missing TypeScript types	Run tsc --emitDeclarationOnly
Expecting advanced HMR	esbuild HMR is basic	Use Vite's dev server for HMR
Not specifying target	Wrong output format	Set target: ['es2020'] explicitly
Missing bundle analysis	Unknown bundle size	Use metafile and analyzeMetafile

Quick Troubleshooting

Issue	Cause	Solution
"Cannot find module"	Missing external	Add to external array
No type definitions	esbuild doesn't generate	Use tsc --emitDeclarationOnly
Large bundle	Not externalizing deps	Mark peer deps as external
Wrong module format	Incorrect format setting	Set format: 'esm' or 'cjs'
Slow builds (unexpected)	Not using esbuild efficiently	Check for plugins causing slowdown
CSS not bundled	No CSS loader	esbuild bundles CSS by default, check import

Performance

# Benchmark (10K modules)
# esbuild: ~0.3s
# Rollup:  ~10s
# Webpack: ~30s

Checklist

• Target browsers/node configured
• External packages for libraries
• Minify + sourcemap for production
• Metafile for bundle analysis
• tsc to generate .d.ts

Further Reading

For advanced configurations: mcp__documentation__fetch_docs

• Technology: esbuild
• esbuild Docs