Bundler

Use Bun's native bundler through the bun build CLI command or the Bun.build() JavaScript API.

At a Glance#

• JS API: await Bun.build({ entrypoints, outdir })
• CLI: bun build <entry> --outdir ./out
• Watch: --watch for incremental rebuilds
• Targets: --target browser|bun|node
• Formats: --format esm|cjs|iife (experimental for cjs/iife)

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './build',
});

bun build ./index.tsx --outdir ./build

It's fast. The following numbers are from esbuild's three.js benchmark.

Why bundle?#

Bundlers solve several problems:

• Reducing HTTP requests. A single package in node_modules may consist of hundreds of files, and large applications may have dozens of such dependencies. Loading each of these files with a separate HTTP request becomes untenable, so bundlers convert your application source code into a smaller number of self-contained "bundles" that can be loaded with a single request.
• Code transforms. Modern apps are commonly built with languages or tools like TypeScript, JSX, and CSS modules. All of these must be converted into plain JavaScript and CSS before a browser can consume them. The bundler is the natural place to configure these transformations.
• Framework features. Frameworks rely on bundler plugins & code transformations to implement common patterns like file-system routing, client-server code co-location (think getServerSideProps or Remix loaders), and server components.
• Full-stack Applications. Bun's bundler can handle both server and client code in a single command, enabling optimized production builds and single-file executables. With build-time HTML imports, you can bundle your entire application — frontend assets and backend server — into a single deployable unit.

Basic example#

Build your first bundle. You have the following two files, which implement a client-side rendered React app.

import * as ReactDOM from "react-dom/client";
import { Component } from "./Component";

const root = ReactDOM.createRoot(document.getElementById("root")!);
root.render(<Component message="Sup!" />);

export function Component(props: { message: string }) {
  return <h1>{props.message}</h1>;
}

Here, index.tsx is the "entrypoint" to the application: the file the bundler starts from. Commonly, this is a script that performs some side effect, like starting a server or, in this case, initializing a React root. Because these files use TypeScript and JSX, the code must be bundled before it can be sent to the browser.

To create the bundle:

await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
});

bun build ./index.tsx --outdir ./out

For each file specified in entrypoints, Bun generates a new bundle and writes it to the ./out directory (as resolved from the current working directory). After running the build, the file system looks like this:

.
├── index.tsx
├── Component.tsx
└── out
    └── index.js

The contents of out/index.js look something like this:

// out/index.js
// ...
// ~20k lines of code
// including the contents of `react-dom/client` and all its dependencies
// this is where the $jsxDEV and $createRoot functions are defined

// Component.tsx
function Component(props) {
  return $jsxDEV(
    "h1",
    {
      children: props.message,
    },
    undefined,
    false,
    undefined,
    this,
  );
}

// index.tsx
var rootNode = document.getElementById("root");
var root = $createRoot(rootNode);
root.render(
  $jsxDEV(
    Component,
    {
      message: "Sup!",
    },
    undefined,
    false,
    undefined,
    this,
  ),
);

Watch mode#

Like the runtime and test runner, the bundler supports watch mode natively.

bun build ./index.tsx --outdir ./out --watch

Content types#

Like the Bun runtime, the bundler supports a range of file types by default. The following table lists the bundler's standard "loaders". See loaders.

Assets#

If the bundler encounters an import with an unrecognized extension, it treats the imported file as an external file. The bundler copies the referenced file as-is into outdir and resolves the import as a path to the file.

// bundle entrypoint
import logo from "./logo.svg";
console.log(logo);

// bundled output
var logo = "./logo-a7305bdef.svg";
console.log(logo);

The exact behavior of the file loader also depends on naming and publicPath.

Plugins#

Plugins can override or extend the behavior described in this table. See loaders.

API#

entrypoints#

An array of paths corresponding to the entrypoints of your application. Bun generates one bundle per entrypoint.

const result = await Bun.build({
  entrypoints: ["./index.ts"],
});
// => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

bun build ./index.ts

files#

A map of file paths to their contents for in-memory bundling: bundle virtual files that don't exist on disk, or override the contents of files that do. This option is only available in the JavaScript API.

You can provide file contents as a string, Blob, TypedArray, or ArrayBuffer.

Bundle entirely from memory#

You can bundle code without any files on disk by providing all sources in files:

const result = await Bun.build({
  entrypoints: ["/app/index.ts"],
  files: {
    "/app/index.ts": `
      import { greet } from "./greet.ts";
      console.log(greet("World"));
    `,
    "/app/greet.ts": `
      export function greet(name: string) {
        return "Hello, " + name + "!";
      }
    `,
  },
});

const output = await result.outputs[0].text();
console.log(output);

When all entrypoints are in the files map, Bun uses the current working directory as the root.

Override files on disk#

In-memory files take priority over files on disk, so you can override specific files while keeping the rest of your codebase unchanged:

// Assume ./src/config.ts exists on disk with development settings
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // Override config.ts with production values
    "./src/config.ts": `
      export const API_URL = "https://api.production.com";
      export const DEBUG = false;
    `,
  },
  outdir: "./dist",
});

Mix disk and virtual files#

Real files on disk can import virtual files, and virtual files can import real files:

// ./src/index.ts exists on disk and imports "./generated.ts"
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // Provide a virtual file that index.ts imports
    "./src/generated.ts": `
      export const BUILD_ID = "${crypto.randomUUID()}";
      export const BUILD_TIME = ${Date.now()};
    `,
  },
  outdir: "./dist",
});

Use this for code generation, injecting build-time constants, or testing with mock modules.

outdir#

The directory where output files are written.

const result = await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './out'
});
// => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

bun build ./index.ts --outdir ./out

If you don't pass outdir to the JavaScript API, Bun does not write bundled code to disk. It returns the bundled files in an array of BuildArtifact objects. These objects are Blobs with extra properties; see Outputs.

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

for (const res of result.outputs) {
  // Can be consumed as blobs
  await res.text();

  // Bun sets Content-Type and Etag headers
  new Response(res);

  // Can be written manually, but you should use `outdir` in this case.
  Bun.write(path.join("out", res.path), res);
}

When outdir is set, the path property on a BuildArtifact is the absolute path it was written to.

target#

The intended execution environment for the bundle.

await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './out',
  target: 'browser', // default
})

bun build ./index.ts --outdir ./out --target browser

Depending on the target, Bun applies different module resolution rules and optimizations.

format#

Specifies the module format of the generated bundles.

Bun defaults to "esm", and provides experimental support for "cjs" and "iife".

format: "esm" - ES Module#

The default format. Supports ES Module syntax, including top-level await and import.meta.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  format: "esm",
})

bun build ./index.tsx --outdir ./out --format esm

To use ES Module syntax in browsers, set format to "esm" and load the bundle with a <script type="module"> tag.

format: "cjs" - CommonJS#

To build a CommonJS module, set format to "cjs". When you choose "cjs", the default target changes from "browser" (esm) to "node" (cjs). CommonJS modules transpiled with format: "cjs", target: "node" run in both Bun and Node.js (assuming both support the APIs in use).

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  format: "cjs",
})

bun build ./index.tsx --outdir ./out --format cjs

format: "iife" - IIFE#

To build an IIFE bundle, set format to "iife". Bun wraps the bundle in an immediately invoked function expression and does not support exposing its exports under a global name.

jsx#

Configures how JSX is compiled.

Classic runtime example (uses factory and fragment):

await Bun.build({
  entrypoints: ["./app.tsx"],
  outdir: "./out",
  jsx: {
    factory: "h",
    fragment: "Fragment",
    runtime: "classic",
  },
});

# JSX configuration is handled via bunfig.toml or tsconfig.json
bun build ./app.tsx --outdir ./out

Automatic runtime example (uses importSource):

await Bun.build({
  entrypoints: ["./app.tsx"],
  outdir: "./out",
  jsx: {
    importSource: "preact",
    runtime: "automatic",
  },
});

# JSX configuration is handled via bunfig.toml or tsconfig.json
bun build ./app.tsx --outdir ./out

splitting#

Whether to enable code splitting.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  splitting: false, // default
})

bun build ./index.tsx --outdir ./out --splitting

When true, the bundler enables code splitting. When multiple entrypoints import the same file or module, the bundler can split that shared code into a separate bundle, known as a chunk. Consider the following files:

import { shared } from "./shared.ts";
console.log(shared);

import { shared } from "./shared.ts";
console.log(shared);

export const shared = "shared";

To bundle entry-a.ts and entry-b.ts with code-splitting enabled:

await Bun.build({
  entrypoints: ['./entry-a.ts', './entry-b.ts'],
  outdir: './out',
  splitting: true,
})

bun build ./entry-a.ts ./entry-b.ts --outdir ./out --splitting

Running this build with the JavaScript API results in the following files:

.
├── entry-a.ts
├── entry-b.ts
├── shared.ts
└── out
    ├── entry-a.js
    ├── entry-b.js
    └── chunk-dqmx6gc8.js

The generated chunk-dqmx6gc8.js file contains the shared code. To avoid collisions, the file name includes a content hash by default. The bun build CLI names this chunk entry-a-t268ez5g.js instead of chunk-<hash>.js. Customize this with naming.

plugins#

A list of plugins to use during bundling.

await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  plugins: [
    /* ... */
  ],
});

The runtime and the bundler share Bun's plugin system. See plugins.

env#

Controls how environment variables are handled during bundling. Internally, this option uses define to inject environment variables into the bundle; env is a shorthand for specifying which ones.

env: "inline"#

Injects environment variables into the bundled output by converting process.env.FOO references to string literals containing the actual environment variable values.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  env: "inline",
})

bun build ./index.tsx --outdir ./out --env inline

For the input below:

// input.js
console.log(process.env.FOO);
console.log(process.env.BAZ);

The generated bundle contains the following code:

// output.js
console.log("bar");
console.log("123");

env: "PUBLIC_*" (prefix)#

Inlines environment variables matching the given prefix (the part before the * character), replacing process.env.FOO with the actual environment variable value. Use a prefix to inline public values, like public-facing URLs or client-side tokens, without injecting private credentials into output bundles.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  
  // Inline all env vars that start with "ACME_PUBLIC_"
  env: "ACME_PUBLIC_*",
})

bun build ./index.tsx --outdir ./out --env ACME_PUBLIC_*

For example, given the following environment variables:

FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com

And source code:

console.log(process.env.FOO);
console.log(process.env.ACME_PUBLIC_URL);
console.log(process.env.BAZ);

The generated bundle contains the following code:

console.log(process.env.FOO);
console.log("https://acme.com");
console.log(process.env.BAZ);

env: "disable"#

Disables environment variable injection entirely.

sourcemap#

Specifies the type of sourcemap to generate.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  sourcemap: 'linked', // default 'none'
})

bun build ./index.tsx --outdir ./out --sourcemap=linked

The associated *.js.map sourcemap is a JSON file containing an equivalent debugId property.

minify#

Whether to enable minification. Default false.

To enable all minification options:

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  minify: true, // default false
})

bun build ./index.tsx --outdir ./out --minify

To granularly enable certain minifications:

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  },
})

bun build ./index.tsx --outdir ./out --minify-whitespace --minify-identifiers --minify-syntax

external#

A list of import paths to consider external. Defaults to [].

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ["lodash", "react"], // default: []
})

bun build ./index.tsx --outdir ./out --external lodash --external react

An external import is not included in the final bundle. Instead, the bundler leaves the import statement as-is, to be resolved at runtime.

For instance, consider the following entrypoint file:

import _ from "lodash";
import { z } from "zod";

const value = z.string().parse("Hello world!");
console.log(_.upperCase(value));

Normally, bundling index.tsx would generate a bundle containing the entire source code of the "zod" package. To leave the import statement as-is instead, mark it as external:

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ['zod'],
})

bun build ./index.tsx --outdir ./out --external zod

The generated bundle looks something like this:

import { z } from "zod";

// ...
// the contents of the "lodash" package
// including the `_.upperCase` function

var value = z.string().parse("Hello world!");
console.log(_.upperCase(value));

To mark all imports as external, use the wildcard *:

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ['*'],
})

bun build ./index.tsx --outdir ./out --external '*'

packages#

Controls whether package dependencies are included in the bundle. Possible values: bundle (default), external. Bun treats any import whose path does not start with ., .., or / as a package.

await Bun.build({
  entrypoints: ['./index.ts'],
  packages: 'external',
})

bun build ./index.ts --packages external

naming#

Customizes the generated file names. Defaults to [dir]/[name].[ext].

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: "[dir]/[name].[ext]", // default
})

bun build ./index.tsx --outdir ./out --entry-naming "[dir]/[name].[ext]"

By default, the names of the generated bundles are based on the name of the associated entrypoint.

.
├── index.tsx
└── out
    └── index.js

With multiple entrypoints, the generated file hierarchy reflects the directory structure of the entrypoints.

.
├── index.tsx
└── nested
    └── index.tsx
└── out
    ├── index.js
    └── nested
        └── index.js

The naming field customizes the names and locations of the generated files. It accepts a template string. Bun uses the template for all bundles that correspond to entrypoints and replaces the following tokens with their values:

• [name] - The name of the entrypoint file, without the extension.
• [ext] - The extension of the generated bundle.
• [hash] - A hash of the bundle contents.
• [dir] - The relative path from the project root to the parent directory of the source file.

For example:

Combine these tokens to create a template string. For instance, to include the hash in the generated bundle names:

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: 'files/[dir]/[name]-[hash].[ext]',
})

bun build ./index.tsx --outdir ./out --entry-naming 'files/[dir]/[name]-[hash].[ext]'

This build would result in the following file structure:

.
├── index.tsx
└── out
    └── files
        └── index-a1b2c3d4.js

When you provide a string for the naming field, Bun uses it only for bundles that correspond to entrypoints. The names of chunks and copied assets are not affected. In the JavaScript API, you can specify a separate template string for each type of generated file.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: {
    // default values
    entry: '[dir]/[name].[ext]',
    chunk: '[name]-[hash].[ext]',
    asset: '[name]-[hash].[ext]',
  },
})

bun build ./index.tsx --outdir ./out \
  --entry-naming '[dir]/[name].[ext]' \
  --chunk-naming '[name]-[hash].[ext]' \
  --asset-naming '[name]-[hash].[ext]'

root#

The root directory of the project.

await Bun.build({
  entrypoints: ['./pages/a.tsx', './pages/b.tsx'],
  outdir: './out',
  root: '.',
})

bun build ./pages/a.tsx ./pages/b.tsx --outdir ./out --root .

If unspecified, Bun uses the first common ancestor of all entrypoint files as the root. Consider the following file structure:

.
└── pages
  └── index.tsx
  └── settings.tsx

Build both entrypoints in the pages directory:

await Bun.build({
  entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
  outdir: './out',
})

bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out

This would result in a file structure like this:

.
└── pages
  └── index.tsx
  └── settings.tsx
└── out
  └── index.js
  └── settings.js

The pages directory is the first common ancestor of the entrypoint files, so Bun treats it as the project root. As a result, the generated bundles live at the top level of the out directory; there is no out/pages directory.

Override this by specifying the root option:

await Bun.build({
  entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
  outdir: './out',
  root: '.',
})

bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out --root .

With . as root, the generated file structure looks like this:

.
└── pages
  └── index.tsx
  └── settings.tsx
└── out
  └── pages
    └── index.js
    └── settings.js

publicPath#

A prefix added to any import paths in bundled code.

In many cases, generated bundles contain no import statements; the goal of bundling is to combine all of the code into a single file. In a few cases, though, the generated bundles contain import statements:

• Asset imports — When importing an unrecognized file type like *.svg, the bundler defers to the file loader, which copies the file into outdir as is. The import is converted into a variable.
• External modules — Files and modules marked as external are not included in the bundle. Instead, the bundler leaves the import statement in the final bundle.
• Chunking. When splitting is enabled, the bundler may generate separate "chunk" files that represent code that is shared among multiple entrypoints.

In any of these cases, the final bundles may contain paths to other files. By default these imports are relative. Here is an example of an asset import:

import logo from "./logo.svg";
console.log(logo);

var logo = "./logo-a7305bdef.svg";
console.log(logo);

Setting publicPath prefixes all file paths with the specified value.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  publicPath: 'https://cdn.example.com/', // default is undefined
})

bun build ./index.tsx --outdir ./out --public-path 'https://cdn.example.com/'

The output file would now look something like this.

var logo = "https://cdn.example.com/logo-a7305bdef.svg";

define#

A map of global identifiers to be replaced at build time. Keys of this object are identifiers or dotted property paths such as process.env.NODE_ENV, and values are JSON strings, identifiers, or property paths that are inlined.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  define: {
    STRING: JSON.stringify("value"),
    "nested.boolean": "true",
  },
})

bun build ./index.tsx --outdir ./out --define STRING='"value"' --define nested.boolean=true

loader#

A map of file extensions to built-in loader names. Use this to customize how certain files are loaded.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  loader: {
    ".png": "dataurl",
    ".txt": "file",
  },
})

bun build ./index.tsx --outdir ./out --loader .png:dataurl --loader .txt:file

banner#

A banner added to the final bundle. This can be a directive like "use client" for React, or a comment block such as a license.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  banner: '"use client";'
})

bun build ./index.tsx --outdir ./out --banner '"use client";'

footer#

A footer added to the final bundle. This can be a comment block for a license or a fun easter egg.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  footer: '// built with love in SF'
})

bun build ./index.tsx --outdir ./out --footer '// built with love in SF'

drop#

Removes function calls from a bundle. For example, --drop=console removes all calls to console.log. Bun also removes the arguments to dropped calls, even if they have side effects. Dropping debugger removes all debugger statements.

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  drop: ["console", "debugger", "anyIdentifier.or.propertyAccess"],
})

bun build ./index.tsx --outdir ./out --drop console --drop debugger

features#

Enable compile-time feature flags for dead code elimination: conditionally include or exclude code paths at bundle time using import { feature } from "bun:bundle".

import { feature } from "bun:bundle";

if (feature("PREMIUM")) {
  // Only included when PREMIUM flag is enabled
  initPremiumFeatures();
}

if (feature("DEBUG")) {
  // Only included when DEBUG flag is enabled
  console.log("Debug mode");
}

await Bun.build({
  entrypoints: ['./app.ts'],
  outdir: './out',
  features: ["PREMIUM"],  // PREMIUM=true, DEBUG=false
})

bun build ./app.ts --outdir ./out --feature PREMIUM

Bun replaces the feature() function with true or false at bundle time. When minification is also enabled, Bun eliminates the unreachable code:

import { feature } from "bun:bundle";
const mode = feature("PREMIUM") ? "premium" : "free";

var mode = "premium";

var mode = "free";

Key behaviors:

• feature() requires a string literal argument — dynamic values are not supported
• Bun completely removes the bun:bundle import from the output
• Works with bun build, bun run, and bun test
• You can enable multiple flags: --feature FLAG_A --feature FLAG_B
• For type safety, augment the Registry interface to restrict feature() to known flags

Use cases:

• Platform-specific code (feature("SERVER") vs feature("CLIENT"))
• Environment-based features (feature("DEVELOPMENT"))
• Gradual feature rollouts
• A/B testing variants
• Paid tier features

Type safety: By default, feature() accepts any string. To get autocomplete and catch typos at compile time, create an env.d.ts file (or add to an existing .d.ts) and augment the Registry interface:

declare module "bun:bundle" {
  interface Registry {
    features: "DEBUG" | "PREMIUM" | "BETA_FEATURES";
  }
}

Ensure the file is included in your tsconfig.json (for example, "include": ["src", "env.d.ts"]). Now feature() only accepts those flags, and invalid strings like feature("TYPO") become type errors.

optimizeImports#

Skip parsing unused submodules of barrel files (re-export index files). When you import only a few named exports from a large library, normally the bundler parses every file the barrel re-exports. With optimizeImports, the bundler parses only the submodules you use.

await Bun.build({
  entrypoints: ["./app.ts"],
  outdir: "./out",
  optimizeImports: ["antd", "@mui/material", "lodash-es"],
});

For example, import { Button } from 'antd' normally parses all ~3000 modules that antd/index.js re-exports. With optimizeImports: ['antd'], the bundler parses only the Button submodule.

This works for pure barrel files — files where every named export is a re-export (export { X } from './x'). If a barrel file has any local exports (export const foo = ...), or if any importer uses import *, the bundler loads all submodules.

The bundler always loads export * re-exports (it never defers them) to avoid circular resolution issues. It defers only named re-exports (export { X } from './x') that no importer uses.

Automatic mode: Packages with "sideEffects": false in their package.json get barrel optimization automatically — no optimizeImports config needed. Use optimizeImports for packages that don't have this field.

Plugins: Resolve and load plugins work with barrel optimization. Deferred submodules go through the plugin pipeline when they are eventually loaded.

metafile#

Generate metadata about the build in a structured format. The metafile describes every input and output file: sizes, imports, and exports. Use it for:

• Bundle analysis: Understand what's contributing to bundle size
• Visualization: Feed into tools like esbuild's bundle analyzer
• Dependency tracking: See the full import graph of your application
• CI integration: Track bundle size changes over time

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

if (result.metafile) {
  // Analyze inputs
  for (const [path, meta] of Object.entries(result.metafile.inputs)) {
    console.log(`${path}: ${meta.bytes} bytes`);
  }

  // Analyze outputs
  for (const [path, meta] of Object.entries(result.metafile.outputs)) {
    console.log(`${path}: ${meta.bytes} bytes`);
  }

  // Save for external analysis tools
  await Bun.write('./dist/meta.json', JSON.stringify(result.metafile));
}

bun build ./src/index.ts --outdir ./dist --metafile=./dist/meta.json

Markdown metafile#

Use --metafile-md to generate a markdown metafile, which is LLM-friendly and readable in the terminal:

bun build ./src/index.ts --outdir ./dist --metafile-md=./dist/meta.md

You can use both --metafile and --metafile-md together:

bun build ./src/index.ts --outdir ./dist --metafile=./dist/meta.json --metafile-md=./dist/meta.md

metafile option formats#

In the JavaScript API, metafile accepts several forms:

// Boolean — include metafile in the result object
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: true,
});

// String — write JSON metafile to a specific path
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: "./dist/meta.json",
});

// Object — specify separate paths for JSON and markdown output
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: {
    json: "./dist/meta.json",
    markdown: "./dist/meta.md",
  },
});

The metafile structure contains:

interface BuildMetafile {
  inputs: {
    [path: string]: {
      bytes: number;
      imports: Array<{
        path: string;
        kind: ImportKind;
        original?: string; // Original specifier before resolution
        external?: boolean;
      }>;
      format?: "esm" | "cjs" | "json" | "css";
    };
  };
  outputs: {
    [path: string]: {
      bytes: number;
      inputs: {
        [path: string]: { bytesInOutput: number };
      };
      imports: Array<{ path: string; kind: ImportKind }>;
      exports: string[];
      entryPoint?: string;
      cssBundle?: string; // Associated CSS file for JS entry points
    };
  };
}

Outputs#

The Bun.build function returns a Promise<BuildOutput>, defined as:

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<object>; // see docs for details
  metafile?: BuildMetafile; // only when metafile: true
}

interface BuildArtifact extends Blob {
  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
  path: string;
  loader: Loader;
  hash: string | null;
  sourcemap: BuildArtifact | null;
}

The outputs array contains all the files generated by the build. Each artifact implements the Blob interface.

const build = await Bun.build({
  /* */
});

for (const output of build.outputs) {
  await output.arrayBuffer(); // => ArrayBuffer
  await output.bytes(); // => Uint8Array
  await output.text(); // string
}

Each artifact also contains the following properties:

Similar to BunFile, BuildArtifact objects can be passed directly into new Response().

const build = await Bun.build({
  /* */
});

const artifact = build.outputs[0];

// Content-Type header is automatically set
return new Response(artifact);

The Bun runtime pretty-prints BuildArtifact objects to help with debugging.

// build.ts
const build = await Bun.build({
  /* */
});

const artifact = build.outputs[0];
console.log(artifact);

bun run build.ts

BuildArtifact (entry-point) {
  path: "./index.js",
  loader: "tsx",
  kind: "entry-point",
  hash: "824a039620219640",
  Blob (74756 bytes) {
    type: "text/javascript;charset=utf-8"
  },
  sourcemap: BuildArtifact (sourcemap) {
    path: "./index.js.map",
    loader: "file",
    kind: "sourcemap",
    hash: "e7178cda3e72e301",
    Blob (24765 bytes) {
      type: "application/json;charset=utf-8"
    },
    sourcemap: null
  }
}

Bytecode#

The bytecode: boolean option generates bytecode for any JavaScript/TypeScript entrypoints, which can greatly improve startup times for large applications. Requires "target": "bun" and a matching version of Bun.

• CommonJS: Works with or without compile: true. Generates a .jsc file alongside each entrypoint.
• ESM: Requires compile: true. Bun embeds the bytecode and module metadata in the standalone executable.

Without an explicit format, bytecode defaults to CommonJS.

// CommonJS bytecode (generates .jsc files)
await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  bytecode: true,
})

// ESM bytecode (requires compile)
await Bun.build({
  entrypoints: ["./index.tsx"],
  outfile: "./mycli",
  bytecode: true,
  format: "esm",
  compile: true,
})

# CommonJS bytecode
bun build ./index.tsx --outdir ./out --bytecode

# ESM bytecode (requires --compile)
bun build ./index.tsx --outfile ./mycli --bytecode --format=esm --compile

Executables#

Bun supports "compiling" a JavaScript/TypeScript entrypoint into a standalone executable. This executable contains a copy of the Bun binary.

bun build ./cli.tsx --outfile mycli --compile
./mycli

See standalone executables.

Logs and errors#

On failure, Bun.build returns a rejected promise with an AggregateError. Log it to the console to pretty-print the error list, or read it programmatically with a try/catch block.

try {
  const result = await Bun.build({
    entrypoints: ["./index.tsx"],
    outdir: "./out",
  });
} catch (e) {
  // TypeScript does not allow annotations on the catch clause
  const error = e as AggregateError;
  console.error("Build Failed");

  // Example: Using the built-in formatter
  console.error(error);

  // Example: Serializing the failure as a JSON string.
  console.error(JSON.stringify(error, null, 2));
}

Most of the time, an explicit try/catch is not needed, as Bun prints uncaught exceptions. You can use a top-level await on the Bun.build call instead.

Each item in error.errors is an instance of BuildMessage or ResolveMessage (subclasses of Error), containing detailed information for each error.

class BuildMessage {
  name: string;
  position?: Position;
  message: string;
  level: "error" | "warning" | "info" | "debug" | "verbose";
}

class ResolveMessage extends BuildMessage {
  code: string;
  referrer: string;
  specifier: string;
  importKind: ImportKind;
}

On build success, the returned object contains a logs property, which contains bundler warnings and info messages.

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

if (result.logs.length > 0) {
  console.warn("Build succeeded with warnings:");
  for (const message of result.logs) {
    // Bun pretty-prints the message object
    console.warn(message);
  }
}

Reference#

interface Bun {
  build(options: BuildOptions): Promise<BuildOutput>;
}

interface BuildConfig {
  entrypoints: string[]; // list of file path
  outdir?: string; // output directory
  target?: Target; // default: "browser"
  /**
   * Output module format. Top-level await is only supported for `"esm"`.
   *
   * Can be:
   * - `"esm"`
   * - `"cjs"` (**experimental**)
   * - `"iife"` (**experimental**)
   *
   * @default "esm"
   */
  format?: "esm" | "cjs" | "iife";
  /**
   * JSX configuration object for controlling JSX transform behavior
   */
  jsx?: {
    runtime?: "automatic" | "classic";
    importSource?: string;
    factory?: string;
    fragment?: string;
    sideEffects?: boolean;
    development?: boolean;
  };
  naming?:
    | string
    | {
        chunk?: string;
        entry?: string;
        asset?: string;
      };
  root?: string; // project root
  splitting?: boolean; // default false, enable code splitting
  plugins?: BunPlugin[];
  external?: string[];
  packages?: "bundle" | "external";
  publicPath?: string;
  define?: Record<string, string>;
  loader?: { [k in string]: Loader };
  sourcemap?: "none" | "linked" | "inline" | "external" | boolean; // default: "none", true -> "inline"
  /**
   * package.json `exports` conditions used when resolving imports
   *
   * Equivalent to `--conditions` in `bun build` or `bun run`.
   *
   * https://nodejs.org/api/packages.html#exports
   */
  conditions?: Array<string> | string;

  /**
   * Controls how environment variables are handled during bundling.
   *
   * Can be one of:
   * - `"inline"`: Injects environment variables into the bundled output by converting `process.env.FOO`
   *   references to string literals containing the actual environment variable values
   * - `"disable"`: Disables environment variable injection entirely
   * - A string ending in `*`: Inlines environment variables that match the given prefix.
   *   For example, `"MY_PUBLIC_*"` will only include env vars starting with "MY_PUBLIC_"
   */
  env?: "inline" | "disable" | `${string}*`;
  minify?:
    | boolean
    | {
        whitespace?: boolean;
        syntax?: boolean;
        identifiers?: boolean;
      };
  /**
   * Ignore dead code elimination/tree-shaking annotations such as @__PURE__ and package.json
   * "sideEffects" fields. This should only be used as a temporary workaround for incorrect
   * annotations in libraries.
   */
  ignoreDCEAnnotations?: boolean;
  /**
   * Force emitting @__PURE__ annotations even if minify.whitespace is true.
   */
  emitDCEAnnotations?: boolean;

  /**
   * Generate bytecode for the output. This can dramatically improve cold
   * start times, but will make the final output larger and slightly increase
   * memory usage.
   *
   * - CommonJS: works with or without `compile: true`
   * - ESM: requires `compile: true`
   *
   * Without an explicit `format`, defaults to CommonJS.
   *
   * Must be `target: "bun"`
   * @default false
   */
  bytecode?: boolean;
  /**
   * Add a banner to the bundled code such as "use client";
   */
  banner?: string;
  /**
   * Add a footer to the bundled code such as a comment block like
   *
   * `// made with bun!`
   */
  footer?: string;

  /**
   * Drop function calls to matching property accesses.
   */
  drop?: string[];

  /**
   * - When set to `true`, the returned promise rejects with an AggregateError when a build failure happens.
   * - When set to `false`, returns a {@link BuildOutput} with `{success: false}`
   *
   * @default true
   */
  throw?: boolean;

  /**
   * Custom tsconfig.json file path to use for path resolution.
   * Equivalent to `--tsconfig-override` in the CLI.
   */
  tsconfig?: string;

  outdir?: string;
}

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

interface BuildArtifact extends Blob {
  path: string;
  loader: Loader;
  hash: string | null;
  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
  sourcemap: BuildArtifact | null;
}

type Loader =
  | "js"
  | "jsx"
  | "ts"
  | "tsx"
  | "css"
  | "json"
  | "jsonc"
  | "toml"
  | "yaml"
  | "text"
  | "file"
  | "napi"
  | "wasm"
  | "html";

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

declare class ResolveMessage {
  readonly name: "ResolveMessage";
  readonly position: Position | null;
  readonly code: string;
  readonly message: string;
  readonly referrer: string;
  readonly specifier: string;
  readonly importKind:
    | "entry_point"
    | "stmt"
    | "require"
    | "import"
    | "dynamic"
    | "require_resolve"
    | "at"
    | "at_conditional"
    | "url"
    | "internal";
  readonly level: "error" | "warning" | "info" | "debug" | "verbose";

  toString(): string;
}

CLI Usage#

bun build <entry points>

General Configuration#

Output & File Handling#

File Naming#

Bundling Options#

Minification & Optimization#