ESBuild Cheatsheet¶

ESBuild - An Extremely Fast JavaScript Bundler

ESBuild is an extremely fast JavaScript bundler and minifier. It packages up JavaScript and TypeScript code for distribution on the web, and is written in Go which makes it 10-100x faster than other bundlers.

Table of Contents¶

Installation
Basic Usage
Command Line Interface
JavaScript API
Configuration
Entry Points
Output
Loaders
Plugins
External Dependencies
Code Splitting
Tree Shaking
Source Maps
Watch Mode
Development Server
TypeScript Support
JSX and React
CSS and Assets
Optimization
Platform Targets
Advanced Features
Performance
Best Practices

Installation¶

Global Installation¶

# Install ESBuild globally
npm install -g esbuild

# Check version
esbuild --version

Local Installation (Recommended)¶

# Initialize npm project
npm init -y

# Install ESBuild locally
npm install --save-dev esbuild

# Or with Yarn
yarn add --dev esbuild

Package.json Scripts¶

{
  "scripts": {
    "build": "esbuild src/index.js --bundle --outfile=dist/bundle.js",
    "dev": "esbuild src/index.js --bundle --outfile=dist/bundle.js --watch",
    "serve": "esbuild src/index.js --bundle --outfile=dist/bundle.js --servedir=dist"
  }
}

Basic Usage¶

Simple Build¶

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

# Minify the output
esbuild src/index.js --bundle --minify --outfile=dist/bundle.min.js

# Generate source maps
esbuild src/index.js --bundle --sourcemap --outfile=dist/bundle.js

Multiple Entry Points¶

# Multiple files
esbuild src/home.js src/about.js --bundle --outdir=dist

# With different formats
esbuild src/index.js --bundle --format=esm --outfile=dist/index.esm.js
esbuild src/index.js --bundle --format=cjs --outfile=dist/index.cjs.js
esbuild src/index.js --bundle --format=iife --outfile=dist/index.iife.js

TypeScript Support¶

# TypeScript files (no configuration needed)
esbuild src/index.ts --bundle --outfile=dist/bundle.js

# With type checking (requires tsc)
tsc --noEmit && esbuild src/index.ts --bundle --outfile=dist/bundle.js

Command Line Interface¶

Build Options¶

# Basic bundling
esbuild src/index.js --bundle --outfile=dist/bundle.js

# Output directory for multiple files
esbuild src/*.js --bundle --outdir=dist

# Minification
esbuild src/index.js --bundle --minify --outfile=dist/bundle.min.js

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

Format Options¶

# ES modules (default)
esbuild src/index.js --bundle --format=esm --outfile=dist/bundle.esm.js

# CommonJS
esbuild src/index.js --bundle --format=cjs --outfile=dist/bundle.cjs.js

# IIFE (Immediately Invoked Function Expression)
esbuild src/index.js --bundle --format=iife --outfile=dist/bundle.iife.js

# IIFE with global name
esbuild src/index.js --bundle --format=iife --global-name=MyLibrary --outfile=dist/bundle.js

Target Options¶

# Target specific environments
esbuild src/index.js --bundle --target=es2020 --outfile=dist/bundle.js
esbuild src/index.js --bundle --target=node14 --outfile=dist/bundle.js
esbuild src/index.js --bundle --target=chrome90,firefox88 --outfile=dist/bundle.js

# Platform targeting
esbuild src/index.js --bundle --platform=browser --outfile=dist/bundle.js
esbuild src/index.js --bundle --platform=node --outfile=dist/bundle.js
esbuild src/index.js --bundle --platform=neutral --outfile=dist/bundle.js

External Dependencies¶

# Mark packages as external
esbuild src/index.js --bundle --external:react --external:react-dom --outfile=dist/bundle.js

# External with wildcards
esbuild src/index.js --bundle --external:@babel/* --outfile=dist/bundle.js

Loader Options¶

# Specify loaders for file types
esbuild src/index.js --bundle --loader:.png=file --loader:.svg=text --outfile=dist/bundle.js

# Data URL loader
esbuild src/index.js --bundle --loader:.png=dataurl --outfile=dist/bundle.js

# Base64 loader
esbuild src/index.js --bundle --loader:.woff=base64 --outfile=dist/bundle.js

JavaScript API¶

Basic Build API¶

const esbuild = require('esbuild');

// Simple build
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js'
}).catch(() => process.exit(1));

// With async/await
async function build() {
  try {
    await esbuild.build({
      entryPoints: ['src/index.js'],
      bundle: true,
      outfile: 'dist/bundle.js',
      minify: true,
      sourcemap: true
    });
    console.log('Build completed successfully');
  } catch (error) {
    console.error('Build failed:', error);
    process.exit(1);
  }
}

build();

Advanced Build Configuration¶

const esbuild = require('esbuild');

const buildOptions = {
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: process.env.NODE_ENV === 'production',
  sourcemap: process.env.NODE_ENV !== 'production',
  target: ['es2020', 'chrome90', 'firefox88'],
  format: 'esm',
  platform: 'browser',
  external: ['react', 'react-dom'],
  loader: {
    '.png': 'file',
    '.svg': 'text',
    '.css': 'css'
  },
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')
  }
};

esbuild.build(buildOptions).catch(() => process.exit(1));

Multiple Builds¶

const esbuild = require('esbuild');

const builds = [
  // ES module build
  {
    entryPoints: ['src/index.js'],
    bundle: true,
    format: 'esm',
    outfile: 'dist/index.esm.js'
  },
  // CommonJS build
  {
    entryPoints: ['src/index.js'],
    bundle: true,
    format: 'cjs',
    outfile: 'dist/index.cjs.js'
  },
  // IIFE build
  {
    entryPoints: ['src/index.js'],
    bundle: true,
    format: 'iife',
    globalName: 'MyLibrary',
    outfile: 'dist/index.iife.js'
  }
];

Promise.all(builds.map(build => esbuild.build(build)))
  .then(() => console.log('All builds completed'))
  .catch(() => process.exit(1));

Configuration¶

Build Configuration File¶

// build.js
const esbuild = require('esbuild');

const isDev = process.argv.includes('--dev');
const isWatch = process.argv.includes('--watch');

const config = {
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: !isDev,
  sourcemap: isDev,
  target: ['es2020'],
  format: 'esm',
  platform: 'browser',
  loader: {
    '.png': 'file',
    '.jpg': 'file',
    '.svg': 'text',
    '.css': 'css'
  },
  define: {
    'process.env.NODE_ENV': JSON.stringify(isDev ? 'development' : 'production')
  }
};

if (isWatch) {
  esbuild.build({
    ...config,
    watch: {
      onRebuild(error, result) {
        if (error) console.error('Watch build failed:', error);
        else console.log('Watch build succeeded');
      }
    }
  });
} else {
  esbuild.build(config).catch(() => process.exit(1));
}

Environment-specific Configuration¶

// esbuild.config.js
const esbuild = require('esbuild');

const createConfig = (env) => ({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: `dist/bundle.${env}.js`,
  minify: env === 'production',
  sourcemap: env === 'development',
  target: env === 'production' ? ['es2018'] : ['es2020'],
  define: {
    'process.env.NODE_ENV': JSON.stringify(env),
    'process.env.API_URL': JSON.stringify(
      env === 'production' 
        ? 'https://api.production.com' 
        : 'http://localhost:3000'
    )
  }
});

module.exports = { createConfig };

Entry Points¶

Single Entry Point¶

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

Multiple Entry Points¶

esbuild.build({
  entryPoints: ['src/home.js', 'src/about.js', 'src/contact.js'],
  bundle: true,
  outdir: 'dist'
});

Named Entry Points¶

esbuild.build({
  entryPoints: {
    home: 'src/pages/home.js',
    about: 'src/pages/about.js',
    admin: 'src/admin/index.js'
  },
  bundle: true,
  outdir: 'dist'
});

Dynamic Entry Points¶

const glob = require('glob');

const entryPoints = glob.sync('src/pages/*.js').reduce((acc, file) => {
  const name = file.replace('src/pages/', '').replace('.js', '');
  acc[name] = file;
  return acc;
}, {});

esbuild.build({
  entryPoints,
  bundle: true,
  outdir: 'dist'
});

Output¶

Output File¶

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

Output Directory¶

esbuild.build({
  entryPoints: ['src/home.js', 'src/about.js'],
  bundle: true,
  outdir: 'dist',
  entryNames: '[name]-[hash]',
  chunkNames: 'chunks/[name]-[hash]',
  assetNames: 'assets/[name]-[hash]'
});

Public Path¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  publicPath: '/static/'
});

Write to Memory¶

const result = await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  write: false, // Don't write to disk
  outdir: 'dist'
});

// Access output files
result.outputFiles.forEach(file => {
  console.log(file.path, file.text);
});

Loaders¶

Built-in Loaders¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.js': 'js',
    '.jsx': 'jsx',
    '.ts': 'ts',
    '.tsx': 'tsx',
    '.css': 'css',
    '.json': 'json',
    '.txt': 'text',
    '.png': 'file',
    '.jpg': 'file',
    '.gif': 'file',
    '.svg': 'dataurl',
    '.woff': 'base64',
    '.woff2': 'base64'
  }
});

File Loader¶

// Copies files to output directory
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  loader: {
    '.png': 'file',
    '.jpg': 'file',
    '.gif': 'file'
  }
});

// Usage in code
import logoUrl from './logo.png';
document.getElementById('logo').src = logoUrl;

Data URL Loader¶

// Embeds files as data URLs
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.svg': 'dataurl',
    '.png': 'dataurl'
  }
});

// Usage in code
import logo from './logo.svg'; // data:image/svg+xml;base64,...

Text Loader¶

// Imports files as strings
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.txt': 'text',
    '.md': 'text',
    '.sql': 'text'
  }
});

// Usage in code
import readme from './README.md';
console.log(readme); // String content

Base64 Loader¶

// Imports files as base64 strings
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.woff': 'base64',
    '.woff2': 'base64'
  }
});

// Usage in code
import fontData from './font.woff2';
// Base64 encoded string

Plugins¶

Plugin System¶

// Simple plugin
const examplePlugin = {
  name: 'example',
  setup(build) {
    build.onResolve({ filter: /^example:/ }, args => {
      return { path: args.path, namespace: 'example' };
    });

    build.onLoad({ filter: /.*/, namespace: 'example' }, args => {
      return {
        contents: 'export default "This is from the example plugin"',
        loader: 'js'
      };
    });
  }
};

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

File System Plugin¶

const fs = require('fs');
const path = require('path');

const fileSystemPlugin = {
  name: 'file-system',
  setup(build) {
    build.onResolve({ filter: /^fs:/ }, args => {
      return {
        path: path.resolve(args.resolveDir, args.path.slice(3)),
        namespace: 'file-system'
      };
    });

    build.onLoad({ filter: /.*/, namespace: 'file-system' }, args => {
      const contents = fs.readFileSync(args.path, 'utf8');
      return {
        contents: `export default ${JSON.stringify(contents)}`,
        loader: 'js'
      };
    });
  }
};

// Usage: import content from 'fs:./data.txt';

HTTP Plugin¶

const https = require('https');

const httpPlugin = {
  name: 'http',
  setup(build) {
    build.onResolve({ filter: /^https?:\/\// }, args => {
      return { path: args.path, namespace: 'http-url' };
    });

    build.onLoad({ filter: /.*/, namespace: 'http-url' }, args => {
      return new Promise((resolve, reject) => {
        https.get(args.path, res => {
          let data = '';
          res.on('data', chunk => data += chunk);
          res.on('end', () => resolve({
            contents: data,
            loader: 'js'
          }));
        }).on('error', reject);
      });
    });
  }
};

// Usage: import module from 'https://cdn.skypack.dev/lodash';

Environment Variables Plugin¶

const envPlugin = {
  name: 'env',
  setup(build) {
    build.onResolve({ filter: /^env$/ }, args => {
      return { path: args.path, namespace: 'env' };
    });

    build.onLoad({ filter: /.*/, namespace: 'env' }, args => {
      return {
        contents: `export default ${JSON.stringify(process.env)}`,
        loader: 'js'
      };
    });
  }
};

// Usage: import env from 'env';

External Dependencies¶

Basic External¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  external: ['react', 'react-dom', 'lodash']
});

External with Patterns¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  external: [
    'react*', // react, react-dom, react-router, etc.
    '@babel/*', // All @babel packages
    'node:*' // Node.js built-in modules
  ]
});

Conditional External¶

const isProduction = process.env.NODE_ENV === 'production';

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  external: isProduction ? ['react', 'react-dom'] : []
});

Code Splitting¶

Automatic Code Splitting¶

esbuild.build({
  entryPoints: ['src/home.js', 'src/about.js'],
  bundle: true,
  outdir: 'dist',
  splitting: true,
  format: 'esm' // Required for splitting
});

Dynamic Imports¶

// main.js
async function loadModule() {
  const { default: heavyModule } = await import('./heavy-module.js');
  return heavyModule();
}

// ESBuild config
esbuild.build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outdir: 'dist',
  splitting: true,
  format: 'esm'
});

Manual Chunks¶

// Use dynamic imports to create manual chunks
const loadUtils = () => import('./utils');
const loadComponents = () => import('./components');

// ESBuild will automatically create separate chunks

Tree Shaking¶

Automatic Tree Shaking¶

// ESBuild automatically tree-shakes ES modules
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  format: 'esm' // Required for tree shaking
});

Side Effects¶

// package.json
{
  "sideEffects": false // Enable aggressive tree shaking
}

// Or specify files with side effects
{
  "sideEffects": [
    "*.css",
    "./src/polyfills.js"
  ]
}

Tree Shaking Example¶

// utils.js
export function add(a, b) {
  return a + b;
}

export function subtract(a, b) {
  return a - b; // This won't be included if not used
}

// main.js
import { add } from './utils.js'; // Only 'add' is bundled
console.log(add(2, 3));

Source Maps¶

Source Map Options¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: true // External source map
});

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: 'inline' // Inline source map
});

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: 'external' // External source map (same as true)
});

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: 'both' // Both inline and external
});

Source Map Configuration¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  sourcemap: true,
  sourceRoot: '/src', // Source root in source map
  sourcesContent: false // Don't include source content
});

Watch Mode¶

Basic Watch Mode¶

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

Watch with Callbacks¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  watch: {
    onRebuild(error, result) {
      if (error) {
        console.error('Watch build failed:', error);
      } else {
        console.log('Watch build succeeded:', result);
      }
    }
  }
});

Advanced Watch Configuration¶

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

// Start watching
await ctx.watch();

// Stop watching later
await ctx.dispose();

Development Server¶

Basic Development Server¶

# Serve files from a directory
esbuild src/index.js --bundle --outfile=dist/bundle.js --servedir=dist

# Custom port
esbuild src/index.js --bundle --outfile=dist/bundle.js --servedir=dist --serve=8080

Development Server API¶

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

// Start development server
const { host, port } = await ctx.serve({
  servedir: 'dist',
  port: 3000
});

console.log(`Server running at http://${host}:${port}`);

Live Reload Setup¶

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

// Watch and serve
await Promise.all([
  ctx.watch(),
  ctx.serve({
    servedir: 'dist',
    port: 3000
  })
]);

TypeScript Support¶

Basic TypeScript¶

// No configuration needed for basic TypeScript
esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js'
});

TypeScript with Type Checking¶

// ESBuild doesn't type-check, use tsc for that
const { execSync } = require('child_process');

// Type check first
try {
  execSync('tsc --noEmit', { stdio: 'inherit' });
} catch (error) {
  process.exit(1);
}

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

TypeScript Configuration¶

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  target: 'es2020',
  loader: {
    '.ts': 'ts',
    '.tsx': 'tsx'
  }
});

TypeScript Paths¶

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

// ESBuild doesn't resolve TypeScript paths automatically
// Use a plugin or resolve manually
const path = require('path');

esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [{
    name: 'resolve-paths',
    setup(build) {
      build.onResolve({ filter: /^@\// }, args => {
        return {
          path: path.resolve('src', args.path.slice(2))
        };
      });
    }
  }]
});

JSX and React¶

React JSX¶

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.jsx': 'jsx'
  },
  jsx: 'automatic' // React 17+ automatic JSX
});

Custom JSX¶

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  jsx: 'transform',
  jsxFactory: 'h', // Preact
  jsxFragment: 'Fragment'
});

JSX Development¶

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  jsx: 'automatic',
  jsxDev: true, // Development mode
  define: {
    'process.env.NODE_ENV': '"development"'
  }
});

TypeScript + React¶

esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  loader: {
    '.tsx': 'tsx'
  },
  jsx: 'automatic'
});

CSS and Assets¶

CSS Bundling¶

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

// Import CSS in JavaScript
import './styles.css';

CSS Modules (with plugin)¶

const cssModulesPlugin = {
  name: 'css-modules',
  setup(build) {
    build.onLoad({ filter: /\.module\.css$/ }, async (args) => {
      // Implement CSS modules logic
      const css = await fs.promises.readFile(args.path, 'utf8');
      // Process CSS modules...
      return {
        contents: css,
        loader: 'css'
      };
    });
  }
};

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

Asset Handling¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  loader: {
    '.png': 'file',
    '.jpg': 'file',
    '.gif': 'file',
    '.svg': 'file',
    '.woff': 'file',
    '.woff2': 'file'
  },
  assetNames: 'assets/[name]-[hash]'
});

Optimization¶

Minification¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: true, // Minify JavaScript
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true
});

Dead Code Elimination¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  treeShaking: true, // Default for ES modules
  format: 'esm'
});

Define Constants¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  define: {
    'process.env.NODE_ENV': '"production"',
    'DEBUG': 'false',
    'VERSION': '"1.0.0"'
  }
});

Drop Console¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  drop: ['console', 'debugger']
});

Platform Targets¶

Browser Target¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  platform: 'browser',
  target: ['chrome90', 'firefox88', 'safari14']
});

Node.js Target¶

esbuild.build({
  entryPoints: ['src/server.js'],
  bundle: true,
  outfile: 'dist/server.js',
  platform: 'node',
  target: 'node16',
  external: ['fs', 'path', 'http'] // Node.js built-ins
});

Neutral Platform¶

esbuild.build({
  entryPoints: ['src/library.js'],
  bundle: true,
  outfile: 'dist/library.js',
  platform: 'neutral', // Works in any environment
  format: 'esm'
});

Advanced Features¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  banner: {
    js: '/* My Library v1.0.0 */',
    css: '/* Styles for My Library */'
  },
  footer: {
    js: '/* End of bundle */'
  }
});

Inject Code¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  inject: ['./polyfills.js'] // Inject into every file
});

Metafile Generation¶

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

// Analyze bundle
console.log(await esbuild.analyzeMetafile(result.metafile));

// Save metafile
require('fs').writeFileSync('meta.json', JSON.stringify(result.metafile));

Conditions¶

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  conditions: ['development'] // Package.json export conditions
});

Performance¶

Build Performance¶

// Measure build time
const start = Date.now();

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

console.log(`Build took ${Date.now() - start}ms`);

Incremental Builds¶

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

// First build
await ctx.rebuild();

// Subsequent rebuilds are faster
await ctx.rebuild();
await ctx.rebuild();

// Clean up
await ctx.dispose();

Parallel Builds¶

const builds = [
  esbuild.build({
    entryPoints: ['src/client.js'],
    bundle: true,
    outfile: 'dist/client.js',
    platform: 'browser'
  }),
  esbuild.build({
    entryPoints: ['src/server.js'],
    bundle: true,
    outfile: 'dist/server.js',
    platform: 'node'
  })
];

await Promise.all(builds);

Best Practices¶

Project Structure¶

# Recommended structure
src/
├── index.js          # Main entry point
├── components/       # React components
├── utils/           # Utility functions
├── styles/          # CSS files
├── assets/          # Images, fonts, etc.
└── types/           # TypeScript types

Configuration Best Practices¶

// esbuild.config.js
const esbuild = require('esbuild');

const isDev = process.env.NODE_ENV !== 'production';

const baseConfig = {
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  sourcemap: isDev,
  minify: !isDev,
  target: ['es2020'],
  loader: {
    '.png': 'file',
    '.jpg': 'file',
    '.svg': 'file',
    '.css': 'css'
  },
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')
  }
};

// Development config
const devConfig = {
  ...baseConfig,
  watch: true,
  serve: {
    servedir: 'dist',
    port: 3000
  }
};

// Production config
const prodConfig = {
  ...baseConfig,
  drop: ['console', 'debugger'],
  metafile: true
};

module.exports = isDev ? devConfig : prodConfig;

Performance Optimization¶

Use external dependencies for libraries that don't need bundling
Enable tree shaking with ES modules
Use code splitting for large applications
Minimize bundle size with proper loaders
Cache builds with incremental compilation

Development Workflow¶

Use watch mode for development
Enable source maps for debugging
Set up live reload for better DX
Type check separately for TypeScript projects
Use development server for local testing

Production Deployment¶

Minify code for smaller bundles
Drop console statements for cleaner code
Generate metafiles for bundle analysis
Use content hashing for caching
Test builds before deployment

Summary¶

ESBuild is an extremely fast JavaScript bundler that provides excellent performance with minimal configuration. Key features include:

Blazing Fast Speed: 10-100x faster than other bundlers
Zero Configuration: Works out of the box for most projects
TypeScript Support: Built-in TypeScript compilation
Tree Shaking: Automatic dead code elimination
Code Splitting: Support for dynamic imports and splitting
Multiple Formats: ES modules, CommonJS, IIFE, and more
Plugin System: Extensible with custom plugins
Development Server: Built-in development server with live reload

By leveraging ESBuild's speed and simplicity, you can significantly improve your build times while maintaining all the features you need for modern web development.