esbuild: Der Komplette Leitfaden zum Schnellsten Bundler

esbuild is an extremely fast JavaScript and TypeScript bundler written in Go. It handles bundling, minification, transpilation, and tree-shaking at speeds 10-100x faster than traditional tools like Webpack, Rollup, or Parcel. Created by Evan Wallace (co-founder of Figma), esbuild achieves its performance by leveraging parallelism, avoiding unnecessary data transformations, and using a compiled language instead of JavaScript. Whether you need a standalone bundler or a high-speed foundation for tools like Vite and Snowpack, esbuild has become an essential part of the modern JavaScript toolchain.

Why esbuild Is So Fast

esbuild achieves its extraordinary speed through four key architectural decisions that set it apart from every JavaScript-based bundler.

• Written in Go: Go compiles to native machine code and runs without a garbage collector pause storm. JavaScript bundlers run in V8 which has JIT compilation overhead, GC pauses, and single-threaded constraints.
• Massive parallelism: esbuild uses all available CPU cores for parsing, linking, and code generation. Each phase is designed for concurrent execution. JavaScript bundlers are fundamentally limited by the single-threaded event loop.
• Minimal data transformations: esbuild reads source files, parses them once into a compact AST representation, and writes output. It avoids the repeated string-to-AST-to-string conversions that plugin chains in Webpack and Rollup perform.
• Memory efficiency: esbuild uses compact data structures and processes files in a streaming fashion. It avoids holding large intermediate representations in memory, resulting in lower memory usage even for large projects.

# Benchmark: Bundle 1,000 modules (React + TypeScript)
#
# esbuild        0.33s   (Go, parallel)
# Rollup + terser 15.4s   (JS, single-threaded)
# Webpack 5       19.8s   (JS, single-threaded)
# Parcel 2         8.7s   (Rust parser + JS plugins)
#
# esbuild is 47-60x faster than Webpack/Rollup
# for equivalent bundling tasks

Installation

esbuild can be installed as a local npm dependency or globally. It ships platform-specific native binaries, so no compilation step is needed during installation.

# Install as a local dev dependency (recommended)
npm install --save-dev esbuild

# Install globally
npm install -g esbuild

# Verify installation
npx esbuild --version
# 0.24.x

# Using with yarn
yarn add --dev esbuild

# Using with pnpm
pnpm add -D esbuild

CLI Usage

The esbuild CLI is the quickest way to bundle, minify, or transform files. It accepts all major options as command-line flags and is ideal for scripts, CI pipelines, and one-off tasks.

Basic bundling and common CLI flags:

# Bundle a single entry point
npx esbuild src/index.ts --bundle --outfile=dist/bundle.js

# Bundle with ESM output format
npx esbuild src/index.ts --bundle --format=esm --outfile=dist/bundle.mjs

# Bundle for Node.js
npx esbuild src/server.ts --bundle --platform=node --outfile=dist/server.js

# Transpile TypeScript without bundling
npx esbuild src/index.ts --outfile=dist/index.js

# Bundle multiple entry points into an output directory
npx esbuild src/app.ts src/worker.ts --bundle --outdir=dist

# Bundle with JSX for React
npx esbuild src/App.tsx --bundle --jsx=automatic --outfile=dist/app.js

Advanced CLI options for production builds:

# Production build with minification and source maps
npx esbuild src/index.ts \
  --bundle \
  --minify \
  --sourcemap \
  --target=es2020 \
  --format=esm \
  --outfile=dist/bundle.js

# With tree-shaking and external packages
npx esbuild src/index.ts \
  --bundle \
  --minify \
  --tree-shaking=true \
  --external:react \
  --external:react-dom \
  --format=esm \
  --outfile=dist/bundle.js

# With define for environment variables
npx esbuild src/index.ts \
  --bundle \
  --define:process.env.NODE_ENV=\"production\" \
  --define:__VERSION__=\"1.2.3\" \
  --outfile=dist/bundle.js

# Analyze bundle with metafile
npx esbuild src/index.ts --bundle --metafile=meta.json --outfile=dist/bundle.js
npx esbuild --analyze=verbose < meta.json

JavaScript API

The JavaScript API provides programmatic access to esbuild from Node.js scripts, build tools, and custom dev servers. It exposes three main functions: build, transform, and context.

build()

The build function reads files from disk, bundles them, and writes output. It accepts all the same options as the CLI plus additional JavaScript-specific options like plugins.

import * as esbuild from "esbuild";

// Basic build
const result = await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js",
  format: "esm",
  target: "es2020",
  minify: true,
  sourcemap: true,
  metafile: true,
});

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

// Library build with multiple entry points
await esbuild.build({
  entryPoints: ["src/index.ts", "src/utils.ts"],
  bundle: true,
  outdir: "dist",
  format: "esm",
  splitting: true,
  platform: "node",
  target: "node18",
  external: ["express", "pg"],
  packages: "external",
});

transform()

The transform function operates on a single string of code without accessing the file system. It is useful for on-the-fly transpilation in dev servers and editor integrations.

import * as esbuild from "esbuild";

// Transform TypeScript to JavaScript
const tsCode = "const greet = (name: string): string => `Hello \${name}`;";
const result = await esbuild.transform(tsCode, {
  loader: "ts",
  target: "es2020",
});
console.log(result.code);
// const greet = (name) => `Hello \${name}`;

// Minify JavaScript
const minified = await esbuild.transform("const x = 1 + 2;", {
  minify: true,
});
console.log(minified.code); // "const x=3;"

// Transform JSX
const jsx = await esbuild.transform(
  "const App = () => <div>Hello</div>;",
  { loader: "jsx", jsx: "automatic" }
);
console.log(jsx.code);

context()

The context function creates a long-lived build context for watch mode and serve mode. It returns an object with rebuild, watch, serve, and dispose methods.

import * as esbuild from "esbuild";

// Create a long-lived build context
const ctx = await esbuild.context({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outdir: "dist",
  format: "esm",
  sourcemap: true,
});

// Manual rebuild (reuses cached state)
const result = await ctx.rebuild();

// Start watching for file changes
await ctx.watch();
console.log("Watching for changes...");

// Start a dev server on port 8000
const { host, port } = await ctx.serve({
  servedir: "public",
  port: 8000,
});
console.log("Serving at http://" + host + ":" + port);

// Clean up when done
// await ctx.dispose();

Content Types and Loaders

esbuild uses loaders to determine how to process each file type. The loader is selected based on the file extension, but can be overridden using the --loader flag or the loader option in the API. Each loader tells esbuild how to interpret the file content.

• js / jsx — JavaScript and JSX files. JSX syntax is supported in both .js and .jsx files when configured.
• ts / tsx — TypeScript and TSX files. esbuild strips type annotations but does not perform type checking. Use tsc --noEmit alongside esbuild for type safety.
• css — CSS files. esbuild bundles CSS imports, handles @import resolution, and supports CSS modules with the .module.css convention.
• json — JSON files are parsed and inlined as JavaScript objects. Tree-shaking works on individual JSON properties.
• text — Files are imported as a JavaScript string containing the file contents.
• binary — Files are imported as a Uint8Array of the file contents.
• base64 — Files are imported as a base64-encoded string.
• file — Files are copied to the output directory and the import resolves to the output file path.
• dataurl — Files are inlined as a data URL string.

// Configure loaders in the JavaScript API
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outdir: "dist",
  loader: {
    ".png": "file",
    ".svg": "dataurl",
    ".txt": "text",
    ".woff2": "file",
    ".json": "json",
    ".csv": "text",
  },
});

// CLI loader override
// npx esbuild src/index.ts --bundle --loader:.svg=dataurl --loader:.txt=text

Bundling and Output Formats

esbuild supports three output formats that determine how the bundled code is structured. Choosing the right format depends on your target environment and module system.

• ESM: Generates standard ES module output with import/export statements. Best for modern browsers, Node.js with type
• CommonJS: Generates Node.js-style require/module.exports output. Use for Node.js packages that need to support older environments.
• IIFE: Wraps the code in an immediately invoked function expression. Use for script tags in browsers where module loading is not available.

// Build a library with both ESM and CJS outputs
import * as esbuild from "esbuild";

const shared = {
  entryPoints: ["src/index.ts"],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: "es2020",
  external: ["react", "react-dom"],
};

// ESM output
await esbuild.build({
  ...shared,
  format: "esm",
  outfile: "dist/index.mjs",
});

// CommonJS output
await esbuild.build({
  ...shared,
  format: "cjs",
  outfile: "dist/index.cjs",
});

// IIFE output for browsers (global variable)
await esbuild.build({
  ...shared,
  format: "iife",
  globalName: "MyLibrary",
  outfile: "dist/index.global.js",
});

Code Splitting

esbuild supports automatic code splitting for ESM output format. When splitting is enabled, shared modules between multiple entry points are extracted into separate chunk files, and dynamic import() expressions create additional chunks loaded on demand.

// Enable code splitting (ESM format required)
await esbuild.build({
  entryPoints: ["src/home.ts", "src/about.ts"],
  bundle: true,
  splitting: true,
  format: "esm",
  outdir: "dist",
  chunkNames: "chunks/[name]-[hash]",
});

// Dynamic imports also create separate chunks
// src/home.ts
// const module = await import("./heavy-module.ts");
// module.doSomething();

// Output structure:
// dist/
//   home.js           (entry)
//   about.js          (entry)
//   chunks/shared-A1B2.js  (shared code)

Tree-Shaking

esbuild performs tree-shaking (dead code elimination) automatically during bundling. It analyzes the import/export graph and removes code that is never imported or used. Tree-shaking works at the statement level for ES modules and respects the sideEffects field in package.json.

Note: For maximum tree-shaking effectiveness, use ES module syntax (import/export) instead of CommonJS (require/module.exports). CommonJS is dynamic and prevents static analysis of unused exports.

// package.json — Mark the package as side-effect-free
{
  "name": "my-library",
  "sideEffects": false
}

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

// esbuild automatically removes unused exports
// src/utils.ts
// export function usedFunction() { ... }   <-- kept
// export function unusedFunction() { ... }  <-- removed

// Force tree-shaking even without bundle mode
// npx esbuild src/index.ts --tree-shaking=true --outfile=dist/out.js

Minification

esbuild includes a built-in minifier that reduces bundle size by removing whitespace, shortening identifiers, and applying code transformations. The minifier works for both JavaScript and CSS. It can be enabled as a single flag or configured individually for whitespace, identifiers, and syntax.

// Enable all minification
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  minify: true,  // Shorthand for all three below
  outfile: "dist/bundle.js",
});

// Fine-grained minification control
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  minifyWhitespace: true,   // Remove whitespace
  minifyIdentifiers: true,  // Shorten variable names
  minifySyntax: true,       // Simplify expressions
  outfile: "dist/bundle.js",
});

// CSS minification works the same way
// npx esbuild src/styles.css --minify --outfile=dist/styles.min.css

// Minification transforms examples:
// true && x   -->  x
// if (a) b(); else c();  -->  a ? b() : c()
// "use strict" removed in ESM
// Dead code after return/throw removed

Source Maps

Source maps allow debuggers to map bundled/minified code back to the original source files. esbuild supports several source map modes to match different deployment scenarios.

• linked: Generates a separate .map file and adds a sourceMappingURL comment to the output. Standard for production deployments.
• inline: Embeds the entire source map as a base64 data URL inside the output file. Useful for development and small scripts.
• external: Generates a separate .map file but does NOT add a sourceMappingURL comment. Use when you want to upload source maps to an error tracking service without exposing them to end users.
• both: Generates a separate .map file AND embeds an inline source map. Rarely needed.

// Source map modes
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  minify: true,
  outfile: "dist/bundle.js",

  // Option 1: Linked (production — separate .map file)
  sourcemap: true,  // or sourcemap: "linked"

  // Option 2: Inline (development — embedded in output)
  // sourcemap: "inline",

  // Option 3: External (error tracking — no comment)
  // sourcemap: "external",

  // Include source content in the map for offline debugging
  sourcesContent: true,
});

Plugin API

The esbuild plugin API lets you intercept and customize the build process. Plugins can resolve import paths, load file contents, and transform code. The API is designed to be simple and fast, with two main hooks: onResolve and onLoad.

• onResolve: Called when esbuild encounters an import path. Your callback can return a custom path, namespace, or external flag to control how the import is resolved.
• onLoad: Called when esbuild needs to load a file. Your callback returns the file contents and loader type. Use this to support custom file formats, virtual modules, or pre-processing steps.

Here is an example plugin that loads .txt files as ES modules and adds environment variables:

import * as esbuild from "esbuild";
import fs from "fs";

// Plugin: Load .txt files as ES modules
const txtPlugin = {
  name: "txt-loader",
  setup(build) {
    build.onLoad({ filter: /\.txt$/ }, async (args) => {
      const text = await fs.promises.readFile(args.path, "utf8");
      return {
        contents: "export default " + JSON.stringify(text) + ";",
        loader: "js",
      };
    });
  },
};

// Plugin: Replace environment variables at build time
const envPlugin = {
  name: "env-loader",
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: "env-ns",
    }));
    build.onLoad({ filter: /.*/, namespace: "env-ns" }, () => ({
      contents: "export default " + JSON.stringify(process.env) + ";",
      loader: "json",
    }));
  },
};

// Use plugins in build
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js",
  plugins: [txtPlugin, envPlugin],
});

Watch Mode

Watch mode monitors source files for changes and automatically rebuilds when a change is detected. It uses the operating system file watcher for instant notifications rather than polling, making rebuilds near-instantaneous.

// Watch mode using the context API
import * as esbuild from "esbuild";

const ctx = await esbuild.context({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outdir: "dist",
  sourcemap: true,
  logLevel: "info",
});

// Start watching — rebuilds on file changes
await ctx.watch();
console.log("Watching for file changes...");

// To stop watching and clean up:
// await ctx.dispose();

// CLI watch mode
// npx esbuild src/index.ts --bundle --outdir=dist --watch

Serve Mode

The built-in serve mode starts a local HTTP server that serves the build output. It integrates with watch mode so every request triggers a rebuild if any files have changed. This provides a minimal development server without needing additional tooling.

// Serve mode with watch integration
import * as esbuild from "esbuild";

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

// Start the dev server
const { host, port } = await ctx.serve({
  servedir: "public",
  port: 3000,
  fallback: "public/index.html", // SPA fallback
});

console.log("Dev server: http://" + host + ":" + port);

// Every HTTP request triggers a rebuild if files changed
// No need to call ctx.watch() separately

// CLI serve mode
// npx esbuild src/index.ts --bundle --outdir=public/dist --servedir=public --serve=3000

Target Environments

The target option tells esbuild which JavaScript version to output. esbuild automatically transforms modern syntax down to the specified target. Supported targets include ESNext, ES2015-ES2022, Chrome, Firefox, Safari, Edge, Node, iOS, and Android version numbers.

// Target a JavaScript version
await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  target: "es2020",
  outfile: "dist/bundle.js",
});

// Target specific browsers
// target: ["chrome90", "firefox88", "safari14", "edge90"]
// Target Node.js: target: "node18"
// Target latest: target: "esnext"

// Syntax transforms based on target:
// Optional chaining (?.)   -> target < es2020
// Nullish coalescing (??)  -> target < es2020
// Class fields             -> target < es2022
// Async/await              -> target < es2017

Platform Configuration

The platform option tells esbuild whether the code will run in the browser or in Node.js. This affects default settings for main fields, conditions, and built-in modules. Setting platform to "node" marks Node.js built-in modules as external by default. Setting platform to "browser" enables import.meta.url and ignores Node.js built-ins.

// Browser platform (default) — resolves "browser" field in package.json
await esbuild.build({
  entryPoints: ["src/app.ts"],
  bundle: true,
  platform: "browser",
  outfile: "dist/app.js",
});

// Node.js platform — marks fs, path, crypto as external
await esbuild.build({
  entryPoints: ["src/server.ts"],
  bundle: true,
  platform: "node",
  target: "node18",
  outfile: "dist/server.js",
});

// Neutral platform — no defaults, full control
// platform: "neutral"

Define and Environment Variables

The define option lets you replace global identifiers with constant expressions at build time. This is commonly used for environment variables, feature flags, and conditional compilation. The replacement happens at the AST level, so it works with tree-shaking to eliminate dead code branches.

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js",
  define: {
    "process.env.NODE_ENV": '"production"',
    "__DEV__": "false",
    "__VERSION__": '"1.2.3"',
    "process.env.API_URL": '"https://api.example.com"',
  },
});

// In source code, this enables dead code elimination:
//
// if (process.env.NODE_ENV === "development") {
//   // This entire block is removed in production
//   enableDevTools();
// }
//
// if (__DEV__) {
//   console.log("debug info"); // Removed
// }

// CLI equivalent:
// npx esbuild src/index.ts --bundle \
//   --define:process.env.NODE_ENV=\"production\" \
//   --define:__DEV__=false

esbuild vs Webpack vs Rollup vs Vite

Understanding how esbuild compares to other bundlers helps you choose the right tool for your project. Each tool has different strengths and trade-offs.

esbuild excels at raw build speed, library bundling, and as a fast transpiler inside other tools. Webpack is best for complex applications needing full plugin ecosystems. Rollup is ideal for library publishing with advanced tree-shaking. Vite combines esbuild speed for development with Rollup quality for production.

Best Practices

• Use esbuild for library bundling where speed and simple configuration matter most. For complex web applications, consider Vite which uses esbuild under the hood.
• Always run tsc --noEmit separately for type checking. esbuild strips types but does not validate them.
• Use the context API with watch mode for development instead of calling build repeatedly. The context reuses internal state for faster incremental rebuilds.
• Set the target option to match your minimum supported environment. This ensures esbuild transforms only the syntax features your targets do not support.
• Use the metafile option to analyze bundle composition. The generated JSON shows file sizes, import chains, and module duplication.
• Enable tree-shaking by using ES module syntax and setting the sideEffects field in package.json to help esbuild eliminate unused code.
• Use define for compile-time constants and environment variables. This enables dead code elimination for conditional branches.
• For production builds, enable minification, source maps (linked mode), and set the appropriate target and platform options.

// Complete production build script (build.mjs)
import * as esbuild from "esbuild";

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

const result = await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outdir: "dist",
  format: "esm",
  splitting: true,
  target: "es2020",
  platform: "browser",
  minify: isProduction,
  sourcemap: isProduction ? "linked" : "inline",
  metafile: true,
  define: {
    "process.env.NODE_ENV": isProduction ? '"production"' : '"development"',
  },
  loader: {
    ".png": "file",
    ".svg": "dataurl",
    ".woff2": "file",
  },
  chunkNames: "chunks/[name]-[hash]",
  assetNames: "assets/[name]-[hash]",
});

if (isProduction) {
  const analysis = await esbuild.analyzeMetafile(result.metafile);
  console.log(analysis);
}

Frequently Asked Questions