secondsky/claude-skills / plugins/bun/skills/bun-bundler
bun-bundler
VerifiedThis skill should be used when the user asks about "bun build", "Bun.build", "bundling with Bun", "code splitting", "tree shaking", "minification", "sourcemaps", "bundle optimization", "esbuild alternative", "building for production", "bundling TypeScript", "bundling for browser", "bundling for Node", or JavaScript/TypeScript bundling with Bun.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
| references/options.md | markdown | 5.2 KB |
SKILL.md
View on GitHub---
name: bun-bundler
description: This skill should be used when the user asks about "bun build", "Bun.build", "bundling with Bun", "code splitting", "tree shaking", "minification", "sourcemaps", "bundle optimization", "esbuild alternative", "building for production", "bundling TypeScript", "bundling for browser", "bundling for Node", or JavaScript/TypeScript bundling with Bun.
metadata:
version: "1.0.0"
license: MIT
---
# Bun Bundler
Bun's bundler is a fast JavaScript/TypeScript bundler built on the same engine as Bun's runtime. It's an esbuild-compatible alternative with native performance.
## Quick Start
### CLI
```bash
# Basic bundle
bun build ./src/index.ts --outdir ./dist
# Production build
bun build ./src/index.ts --outdir ./dist --minify
# Multiple entry points
bun build ./src/index.ts ./src/worker.ts --outdir ./dist
```
### JavaScript API
```typescript
// Since Bun 1.2, Bun.build REJECTS on failure (throws).
// Wrap in try/catch to handle errors; pass { throw: false } to restore the
// old resolve-with-{ success, logs } contract if you prefer that style.
try {
const result = await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
});
console.log(`Built ${result.outputs.length} files`);
} catch (err) {
console.error("Build failed:", err);
process.exit(1);
}
```
## Bun.build Options
```typescript
await Bun.build({
// Entry points (required)
entrypoints: ["./src/index.ts"],
// Output directory
outdir: "./dist",
// Target environment
target: "browser", // "browser" | "bun" | "node"
// Output format
format: "esm", // "esm" | "cjs" | "iife"
// Minification
minify: true, // or { whitespace: true, identifiers: true, syntax: true }
// Code splitting
splitting: true,
// Source maps
sourcemap: "external", // "none" | "inline" | "external" | "linked"
// Naming patterns
naming: {
entry: "[dir]/[name].[ext]",
chunk: "[name]-[hash].[ext]",
asset: "[name]-[hash].[ext]",
},
// Define globals
define: {
"process.env.NODE_ENV": JSON.stringify("production"),
},
// External packages
external: ["react", "react-dom"],
// Loaders
loader: {
".svg": "text",
".png": "file",
},
// Plugins
plugins: [myPlugin],
// Root directory
root: "./src",
// Public path for assets
publicPath: "/static/",
});
```
## CLI Flags
```bash
bun build <entrypoints> [flags]
```
| Flag | Description |
|------|-------------|
| `--outdir` | Output directory |
| `--outfile` | Output single file |
| `--target` | `browser`, `bun`, `node` |
| `--format` | `esm`, `cjs`, `iife` |
| `--minify` | Enable minification |
| `--minify-whitespace` | Minify whitespace only |
| `--minify-identifiers` | Minify identifiers only |
| `--minify-syntax` | Minify syntax only |
| `--splitting` | Enable code splitting |
| `--sourcemap` | `none`, `inline`, `external`, `linked` |
| `--external` | Mark packages as external |
| `--define` | Define compile-time constants |
| `--loader` | Custom loaders for extensions |
| `--public-path` | Public path for assets |
| `--root` | Root directory |
| `--entry-naming` | Entry point naming pattern |
| `--chunk-naming` | Chunk naming pattern |
| `--asset-naming` | Asset naming pattern |
## Target Environments
### Browser (default)
```typescript
await Bun.build({
entrypoints: ["./src/index.ts"],
target: "browser",
outdir: "./dist",
});
```
### Bun Runtime
```typescript
await Bun.build({
entrypoints: ["./src/server.ts"],
target: "bun",
outdir: "./dist",
});
```
### Node.js
```typescript
await Bun.build({
entrypoints: ["./src/server.ts"],
target: "node",
outdir: "./dist",
});
```
## Code Splitting
```typescript
await Bun.build({
entrypoints: ["./src/index.ts", "./src/admin.ts"],
splitting: true,
outdir: "./dist",
});
```
Shared dependencies are extracted into separate chunks automatically.
## Loaders
| Loader | Extensions | Output |
|--------|------------|--------|
| `js` | `.js`, `.mjs`, `.cjs` | JavaScript |
| `jsx` | `.jsx` | JavaScript |
| `ts` | `.ts`, `.mts`, `.cts` | JavaScript |
| `tsx` | `.tsx` | JavaScript |
| `json` | `.json` | JavaScript |
| `toml` | `.toml` | JavaScript |
| `text` | - | String export |
| `file` | - | File path export |
| `base64` | - | Base64 string |
| `dataurl` | - | Data URL |
| `css` | `.css` | CSS file |
Custom loaders:
```typescript
await Bun.build({
entrypoints: ["./src/index.ts"],
loader: {
".svg": "text",
".png": "file",
".woff2": "file",
},
});
```
## Plugins
```typescript
const myPlugin = {
name: "my-plugin",
setup(build) {
// Resolve hook
build.onResolve({ filter: /\.special$/ }, (args) => {
return { path: args.path, namespace: "special" };
});
// Load hook
build.onLoad({ filter: /.*/, namespace: "special" }, (args) => {
return {
contents: `export default "special"`,
loader: "js",
};
});
},
};
await Bun.build({
entrypoints: ["./src/index.ts"],
plugins: [myPlugin],
});
```
## Build Output
```typescript
// Bun 1.2+: Bun.build rejects on failure. Use try/catch to surface build
// errors (or pass { throw: false } and keep the legacy { success, logs } shape).
try {
const result = await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
});
// Access outputs
for (const output of result.outputs) {
console.log(output.path); // File path
console.log(output.kind); // "entry-point" | "chunk" | "asset"
console.log(output.hash); // Content hash
console.log(output.loader); // Loader used
// Read content
const text = await output.text();
}
} catch (err) {
console.error("Build failed:", err);
process.exit(1);
}
```
## Common Patterns
### Production Build
```typescript
await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
target: "browser",
minify: true,
sourcemap: "external",
splitting: true,
define: {
"process.env.NODE_ENV": JSON.stringify("production"),
},
});
```
### Library Build
```typescript
await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
target: "bun",
format: "esm",
external: ["*"], // Externalize all dependencies
sourcemap: "external",
});
```
### Build Script
```typescript
// build.ts
// Bun 1.2+: Bun.build rejects on failure, so try/catch is the modern idiom.
try {
const result = await Bun.build({
entrypoints: ["./src/index.ts"],
outdir: "./dist",
minify: process.env.NODE_ENV === "production",
});
console.log(`Built ${result.outputs.length} files`);
} catch (err) {
console.error("Build failed:", err);
process.exit(1);
}
```
Run: `bun run build.ts`
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| `Could not resolve` | Missing import | Install package or fix path |
| `No matching export` | Named export missing | Check export name |
| `Unexpected token` | Syntax error | Fix source code |
| `Target not supported` | Invalid target | Use `browser`, `bun`, or `node` |
## When to Load References
Load `references/options.md` when:
- Need complete option reference
- Configuring advanced features
Load `references/plugins.md` when:
- Writing custom plugins
- Understanding plugin API
Load `references/macros.md` when:
- Using compile-time macros
- Build-time code generation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |