esbuild — CLI & transform API

What it is

esbuild is the Go-implemented bundler/transformer that set the modern speed baseline. It powers Vite's dev transforms, ships embedded inside most modern toolchains, and works standalone as a CLI or JS API. This page covers the CLI and the JS transform API.

For package context, see packages-npm/npm-esbuild.

Install

npm install -D esbuild
# or
npm install -g esbuild

Output: platform-specific Go binary in node_modules/.bin/esbuild.

Day-to-day commands

Common scenarios

Bundle a CLI for Node

npx esbuild src/cli.ts \
  --bundle \
  --platform=node \
  --target=node20 \
  --outfile=dist/cli.cjs

Output:

  dist/cli.cjs   1.2mb

⚡ Done in 47ms

For a tiny shipping binary, add --minify. For ESM output, --format=esm (and rename to .mjs).

Browser app bundle with code splitting

npx esbuild src/index.ts src/worker.ts \
  --bundle \
  --format=esm \
  --splitting \
  --outdir=dist \
  --minify \
  --target=es2020

Output:

  dist/index.js          12kb
  dist/worker.js          8kb
  dist/chunk-AB12.js      4kb   ← shared chunk

⚡ Done in 89ms

--splitting requires --format=esm (and --outdir, not --outfile).

Transform API (no bundling, no FS)

import { transform } from "esbuild";

const result = await transform(
  "const x: number = 42; export default x;",
  { loader: "ts", target: "es2022" }
);

console.log(result.code);

Output:

const x = 42;
export default x;

transform takes a single string in, returns code + map. No filesystem access. Use for REPLs, AST tools, runtime evaluation.

Watch / context API

import esbuild from "esbuild";

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

await ctx.watch();         // rebuilds on file change
const { host, port } = await ctx.serve({ servedir: "dist" });
console.log(`http://${host}:${port}`);

serve is a minimal HTTP server — no HMR. Use Vite for SPA dev.

Sourcemap modes

npx esbuild src/index.ts --bundle --sourcemap            # external (.map file + comment)
npx esbuild src/index.ts --bundle --sourcemap=inline     # base64 in JS file
npx esbuild src/index.ts --bundle --sourcemap=external   # .map file, no comment
npx esbuild src/index.ts --bundle --sourcemap=linked     # .map file + comment (default)

Output:

  out.js      12.3kb
  out.js.map  18.7kb

⚡ Done in 17ms

For prod: --sourcemap=external + upload to error tracker, or --sourcemap=linked + serve maps privately.

Plugin (JS API only)

import esbuild from "esbuild";

const envPlugin = {
  name: "env",
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: "env-ns",
    }));
    build.onLoad({ filter: /.*/, namespace: "env-ns" }, () => ({
      contents: JSON.stringify(process.env),
      loader: "json",
    }));
  },
};

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

esbuild's plugin API is intentionally small: onResolve, onLoad, onStart, onEnd. Not a webpack-style hook ladder.

Mark deps external

npx esbuild src/index.ts --bundle --platform=node \
  --external:express --external:pg --outfile=dist/out.js

Output:

  dist/out.js  8.2kb

⚡ Done in 11ms

Or for all of node_modules/:

npx esbuild src/index.ts --bundle --platform=node \
  --packages=external --outfile=dist/out.js

Output:

  dist/out.js  4.7kb

⚡ Done in 9ms

The --packages=external flag (0.18+) externalises every npm package, leaving only your source bundled.

Respect tsconfig.json

npx esbuild src/index.ts --bundle --tsconfig=tsconfig.json --outfile=dist/out.js

Output:

  dist/out.js  18.4kb

⚡ Done in 21ms

esbuild reads target, paths, experimentalDecorators, useDefineForClassFields. Without --tsconfig, it falls back to its own defaults.

Useful flags

Configuration

esbuild has no config file. Either pass flags on the CLI or write a build.mjs:

// build.mjs
import esbuild from "esbuild";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  platform: "browser",
  format: "esm",
  outdir: "dist",
  splitting: true,
  minify: true,
  target: ["es2020", "chrome110", "firefox110"],
  sourcemap: true,
  define: {
    "process.env.NODE_ENV": '"production"',
  },
  loader: { ".png": "file", ".svg": "text" },
  metafile: true,
});

node build.mjs

Output:

  dist/index.js     12kb
  dist/chunk-AB.js   4kb

⚡ Done in 89ms

The JS API is more flexible than the CLI — multi-entry, plugin chains, metafile inspection.

Common pitfalls

1. [ERROR] Could not resolve "X". Either missing install, missing --platform=node for Node deps, or a tsconfig.json path alias not loaded (pass --tsconfig).
2. Top-level await is not available in the configured target environment. Bump --target=es2022+ or refactor.
3. The CommonJS "require" function does not work in ESM scope. Output is ESM but source uses require(). Switch source, change --format=cjs, or add a createRequire shim.
4. Source maps don't show original source. --sources-content=false was set, or IDE loads bundle from a different URL than sourceMappingURL expects.
5. Bundle includes node_modules/ deps unexpectedly. Default bundles everything. Use --packages=external or per-package --external:X.
6. Binary fails after install. Platform optional dep missing. Run npm install --include=optional or npm rebuild esbuild.
7. Minifier produces slightly larger output than Terser. Expected — esbuild trades ~5% bytes for ~10× speed. Run Terser as a second pass for max compression.

See also

• Packages: npm-esbuild — versioning, security, ecosystem
• JavaScript: modules — ESM/CJS interop
• JavaScript: vite — esbuild-powered dev server