🎯

esbuild

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill esbuild

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/esbuild
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/esbuild/
  • All projects ~/.claude/skills/esbuild/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert esbuild bundler assistance covering blazing-fast Go-based bundling, JSX/TS transforms, minification, and API usage. Use when bundling modern web apps, TypeScript libraries, or Node.js backends.

esbuild

esbuild changed the industry by proving that build tools could be 100x faster if written in Go/Rust. It is not just a bundler but a transpiler.

When to Use

  • Ultra-Fast JavaScript/TypeScript Bundling: Compiling and bundling web applications 10x-100x faster than Webpack or Rollup.
  • Underlying Bundling Engine for Modern Tools: Powering Vite, AWS CDK, and serverless deployment packagers.
  • High-Speed Code Minification: Minifying JS and CSS bundles in CI/CD pipelines with minimal memory overhead.
  • Custom Build Scripts via Go/JS API: Orchestrating complex builds, asset copying, and source map generation programmatically.

Quick Start

# Bundle and minify TypeScript CLI or application in milliseconds
npx esbuild src/index.ts \
  --bundle \
  --platform=node \
  --target=node20 \
  --outfile=dist/bundle.js \
  --minify \
  --sourcemap

Core Concepts

Programmatic Build API with esbuild.build()

Configuring a production bundle script in Node.js:

// build.js
import * as esbuild from "esbuild";

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

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  outfile: "dist/bundle.js",
  platform: "browser",
  target: ["es2022", "chrome100", "firefox100", "safari15"],
  format: "esm",
  minify: isProduction,
  sourcemap: !isProduction,
  treeShaking: true,
  loader: {
    ".png": "dataurl",
    ".svg": "text",
  },
  define: {
    "process.env.NODE_ENV": JSON.stringify(
      process.env.NODE_ENV || "development",
    ),
  },
  logLevel: "info",
});

console.log("Build completed successfully.");

Authoring a Custom esbuild Plugin

Intercepting imports and resolving virtual modules:

const envPlugin = {
  name: "env-virtual-module",
  setup(build) {
    // Intercept import statements matching 'virtual:env'
    build.onResolve({ filter: /^virtual:env$/ }, (args) => ({
      path: args.path,
      namespace: "env-ns",
    }));

    // Return virtual content
    build.onLoad({ filter: /.*/, namespace: "env-ns" }, () => ({
      contents: JSON.stringify({
        BUILD_TIME: new Date().toISOString(),
        VERSION: "2026.1.0",
      }),
      loader: "json",
    }));
  },
};

High-Speed CLI Minification

Minifying assets from command line:

# Minify JavaScript bundle with sourcemap
npx esbuild src/index.ts --bundle --minify --sourcemap --outfile=dist/app.min.js

# Minify CSS stylesheet
npx esbuild styles/main.css --minify --outfile=dist/main.min.css

Common Patterns

Build Script with Watch Mode and Development Server

Problem: Fast iterative local development without heavy Webpack/Vite overhead.

Solution: Use esbuild's asynchronous JavaScript API:

import * as esbuild from "esbuild";

const ctx = await esbuild.context({
  entryPoints: ["src/app.tsx"],
  bundle: true,
  outfile: "public/bundle.js",
  sourcemap: true,
  target: ["es2022"],
});

// Watch files for changes and serve on localhost
await ctx.watch();
const { host, port } = await ctx.serve({ servedir: "public" });
console.log(`Server listening on http://${host}:${port}`);

Best Practices

Do:

  • Target platform: 'neutral' or format: 'esm' for modern library bundling.
  • Enable treeShaking: true to eliminate dead code from external dependencies.
  • Use esbuild.context() when building local development servers with instant hot rebuilding.
  • Use define to statically replace environment variables at build time.

Don't:

  • Rely on esbuild for TypeScript type checking; always run tsc --noEmit alongside esbuild in CI.
  • Use esbuild for legacy ES5 transpilation; esbuild focuses on modern ES2015+ targets.
  • Author complex AST code transformation plugins in esbuild; esbuild intentionally does not expose an AST.

Troubleshooting

ErrorCauseSolution
Dynamic require of "..." is not supportedBundling CommonJS dynamic requires into ESM bundle.Set --platform=node or add external module: --external:module_name.
Type annotations stripped without type checkingesbuild does not type-check (transpiles only).Run tsc --noEmit concurrently in your build script.
Unexpected character in CSS fileBundling CSS without appropriate loader configured.Add --loader:.css=css or --loader:.png=file.

References

More from this repository10