Bun Bundler

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

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

if (!result.success) {
  console.error("Build failed:", result.logs);
}

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]

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

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

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

// Check success
if (!result.success) {
  for (const log of result.logs) {
    console.error(log);
  }
  process.exit(1);
}

// 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();
}

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
const result = await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  minify: process.env.NODE_ENV === "production",
});

if (!result.success) {
  console.error("Build failed");
  process.exit(1);
}

console.log(`Built ${result.outputs.length} files`);

Run: bun run build.ts

Common Errors

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

Bun.build Complete Options Reference

All Options

interface BuildConfig {
  // Entry points
  entrypoints: string[];

  // Output
  outdir?: string;
  outfile?: string;  // Single file output

  // Target
  target?: "browser" | "bun" | "node";

  // Format
  format?: "esm" | "cjs" | "iife";

  // Minification
  minify?: boolean | {
    whitespace?: boolean;
    identifiers?: boolean;
    syntax?: boolean;
  };

  // Code splitting
  splitting?: boolean;

  // Source maps
  sourcemap?: "none" | "inline" | "external" | "linked";

  // Naming
  naming?: {
    entry?: string;
    chunk?: string;
    asset?: string;
  } | string;

  // Root directory
  root?: string;

  // Public path
  publicPath?: string;

  // Define
  define?: Record<string, string>;

  // External
  external?: string[];

  // Loaders
  loader?: Record<string, Loader>;

  // Plugins
  plugins?: Plugin[];

  // Conditions
  conditions?: string[];

  // Drop
  drop?: string[];

  // Banner/Footer
  banner?: string;
  footer?: string;

  // Throw on error
  throw?: boolean;

  // Packages
  packages?: "bundle" | "external";

  // Bytecode (Bun target only)
  bytecode?: boolean;

  // Environment files
  emitDCEAnnotations?: boolean;
  ignoreDCEAnnotations?: boolean;

  // JSX
  jsx?: "automatic" | "classic" | "preserve";
  jsxFactory?: string;
  jsxFragment?: string;
  jsxImportSource?: string;
  jsxSideEffects?: boolean;
}

Entry Points

// Single entry
await Bun.build({
  entrypoints: ["./src/index.ts"],
});

// Multiple entries
await Bun.build({
  entrypoints: [
    "./src/index.ts",
    "./src/worker.ts",
    "./src/admin.ts",
  ],
});

// Glob patterns
await Bun.build({
  entrypoints: ["./src/**/*.entry.ts"],
});

Output

Directory Output

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

Single File Output

await Bun.build({
  entrypoints: ["./src/index.ts"],
  outfile: "./dist/bundle.js",
});

Naming Patterns

await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  naming: {
    entry: "[dir]/[name].[ext]",
    chunk: "chunks/[name]-[hash].[ext]",
    asset: "assets/[name]-[hash].[ext]",
  },
});

Placeholders:

• [name] - Original filename without extension
• [ext] - File extension
• [hash] - Content hash
• [dir] - Relative directory path

Minification

// Full minification
await Bun.build({
  minify: true,
});

// Selective minification
await Bun.build({
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  },
});

// Individual flags
await Bun.build({
  minify: {
    whitespace: true,   // Remove whitespace
    identifiers: false, // Keep variable names
    syntax: true,       // Shorten syntax
  },
});

Source Maps

// No source map
await Bun.build({
  sourcemap: "none",
});

// Inline (in bundle)
await Bun.build({
  sourcemap: "inline",
});

// External (.map file)
await Bun.build({
  sourcemap: "external",
});

// Linked (reference in bundle, separate file)
await Bun.build({
  sourcemap: "linked",
});

Code Splitting

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

Shared modules extracted to chunks automatically.

Define

Replace identifiers at compile time:

await Bun.build({
  define: {
    "process.env.NODE_ENV": JSON.stringify("production"),
    "DEBUG": "false",
    "VERSION": JSON.stringify("1.0.0"),
  },
});

External

Exclude from bundle:

// Specific packages
await Bun.build({
  external: ["react", "react-dom"],
});

// All packages
await Bun.build({
  packages: "external",
});

// Patterns
await Bun.build({
  external: ["@company/*"],
});

Loaders

await Bun.build({
  loader: {
    ".png": "file",
    ".svg": "text",
    ".graphql": "text",
    ".woff2": "file",
    ".css": "css",
    ".json": "json",
    ".txt": "text",
    ".bin": "base64",
  },
});

Loader Types

Conditions

Custom export conditions:

await Bun.build({
  conditions: ["react-server", "production"],
});

Drop

Remove specific constructs:

await Bun.build({
  drop: ["console", "debugger"],
});

Banner/Footer

Add text to output:

await Bun.build({
  banner: "/* Copyright 2024 */",
  footer: "// End of bundle",
});

JSX Configuration

await Bun.build({
  jsx: "automatic",           // or "classic" | "preserve"
  jsxFactory: "h",            // For classic
  jsxFragment: "Fragment",    // For classic
  jsxImportSource: "preact",  // For automatic
  jsxSideEffects: false,      // Tree-shake JSX
});

Bytecode (Bun target)

Pre-compile to bytecode:

await Bun.build({
  target: "bun",
  bytecode: true,
});

Faster startup, obfuscated code.