Skip to content

secondsky/claude-skills / plugins/bun/skills/bun-bundler

bun-bundler

Verified

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.

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

# 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

// 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

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

bun build <entrypoints> [flags]
FlagDescription
--outdirOutput directory
--outfileOutput single file
--targetbrowser, bun, node
--formatesm, cjs, iife
--minifyEnable minification
--minify-whitespaceMinify whitespace only
--minify-identifiersMinify identifiers only
--minify-syntaxMinify syntax only
--splittingEnable code splitting
--sourcemapnone, inline, external, linked
--externalMark packages as external
--defineDefine compile-time constants
--loaderCustom loaders for extensions
--public-pathPublic path for assets
--rootRoot directory
--entry-namingEntry point naming pattern
--chunk-namingChunk naming pattern
--asset-namingAsset naming pattern

Target Environments

Browser (default)

await Bun.build({
  entrypoints: ["./src/index.ts"],
  target: "browser",
  outdir: "./dist",
});

Bun Runtime

await Bun.build({
  entrypoints: ["./src/server.ts"],
  target: "bun",
  outdir: "./dist",
});

Node.js

await Bun.build({
  entrypoints: ["./src/server.ts"],
  target: "node",
  outdir: "./dist",
});

Code Splitting

await Bun.build({
  entrypoints: ["./src/index.ts", "./src/admin.ts"],
  splitting: true,
  outdir: "./dist",
});

Shared dependencies are extracted into separate chunks automatically.

Loaders

LoaderExtensionsOutput
js.js, .mjs, .cjsJavaScript
jsx.jsxJavaScript
ts.ts, .mts, .ctsJavaScript
tsx.tsxJavaScript
json.jsonJavaScript
toml.tomlJavaScript
text-String export
file-File path export
base64-Base64 string
dataurl-Data URL
css.cssCSS file

Custom loaders:

await Bun.build({
  entrypoints: ["./src/index.ts"],
  loader: {
    ".svg": "text",
    ".png": "file",
    ".woff2": "file",
  },
});

Plugins

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

// 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

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

await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  target: "bun",
  format: "esm",
  external: ["*"],  // Externalize all dependencies
  sourcemap: "external",
});

Build Script

// 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

ErrorCauseFix
Could not resolveMissing importInstall package or fix path
No matching exportNamed export missingCheck export name
Unexpected tokenSyntax errorFix source code
Target not supportedInvalid targetUse 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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall