esbuild
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill esbuildRun 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.
/esbuildInstall 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.
SKILL.md
View on GitHub β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'orformat: 'esm'for modern library bundling. - Enable
treeShaking: trueto eliminate dead code from external dependencies. - Use
esbuild.context()when building local development servers with instant hot rebuilding. - Use
defineto statically replace environment variables at build time.
Don't:
- Rely on esbuild for TypeScript type checking; always run
tsc --noEmitalongside 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
| Error | Cause | Solution |
|---|---|---|
Dynamic require of "..." is not supported | Bundling CommonJS dynamic requires into ESM bundle. | Set --platform=node or add external module: --external:module_name. |
Type annotations stripped without type checking | esbuild does not type-check (transpiles only). | Run tsc --noEmit concurrently in your build script. |
Unexpected character in CSS file | Bundling CSS without appropriate loader configured. | Add --loader:.css=css or --loader:.png=file. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill