Bun.build() has no built-in development server
Unlike esbuild, Bun's bundler has no built-in development server. Use it with Bun.serve and other runtime APIs to get the same effect. esbuild's HTTP options do not apply.
bun.build() api core
32 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Bun's bundler performance vs esbuild
Bun's bundler is 1.75x faster than esbuild on esbuild's three.js benchmark when bundling 10 copies of three.js from scratch, with sourcemaps and minification.
entrypoints capitalization in Bun.build() JS API
In Bun.build() JavaScript API, the parameter is spelled "entrypoints" (lowercase 'p'), whereas esbuild uses "entryPoints" (uppercase 'P').
Bundling enabled by default in Bun.build
Unlike esbuild, Bun bundles by default; no --bundle flag is needed. To transpile each file individually, use Bun.Transpiler instead.
target parameter in Bun.build() replaces platform
In Bun.build() JavaScript API, the "platform" parameter is renamed to "target". It supports "bun", "node", and "browser" (the default). It does not support "neutral".
bundle always true in Bun.build()
In Bun.build(), bundle is always true. Use Bun.Transpiler to transpile without bundling.
absWorkingDir always process.cwd() in Bun.build()
In Bun.build(), absWorkingDir is always set to process.cwd() and cannot be changed.
allowOverwrite always false in Bun.build()
In Bun.build(), allowOverwrite is always false. Bun never allows overwriting output files.
color logs returned in build result in Bun.build()
In Bun.build(), color logs are returned in the logs property of the build result, not as CLI output.
Unsupported esbuild JS API options in Bun.build()
The following esbuild options are not supported in Bun.build(): alias, charset, globalName, inject, legalComments, logLevel, logLimit, logOverride, mainFields, mangleCache, mangleProps, mangleQuoted, nodePaths, outExtension, preserveSymlinks, pure, reserveProps, resolveExtensions, sourceRoot, sourcesContent, stdin, supported.
Compile option three forms
The compile option in Bun.build() accepts three forms: boolean (compile for current platform), string (target for cross-compilation), or CompileBuildOptions object (full control with outfile and other options).
CompileTarget type definition
type CompileTarget = | "bun-darwin-x64" | "bun-darwin-x64-baseline" | "bun-darwin-arm64" | "bun-linux-x64" | "bun-linux-x64-baseline" | "bun-linux-x64-modern" | "bun-linux-arm64" | "bun-linux-x64-musl" | "bun-linux-x64-baseline-musl" | "bun-linux-arm64-musl" | "bun-windows-x64" | "bun-windows-x64-baseline" | "bun-windows-x64-modern" | "bun-windows-arm64";
Complete example of Bun.build with compile
import type { BunPlugin } from "bun"; const myPlugin: BunPlugin = { name: "my-plugin", setup(build) { // Plugin implementation }, }; const result = await Bun.build({ entrypoints: ["./src/cli.ts"], compile: { target: "bun-linux-x64", outfile: "./dist/mycli", execArgv: ["--smol"], autoloadDotenv: false, autoloadBunfig: false, }, minify: true, sourcemap: "linked", bytecode: true, define: { "process.env.NODE_ENV": JSON.stringify("production"), VERSION: JSON.stringify("1.0.0"), }, plugins: [myPlugin], });
outdir controls output location and affects return value
The outdir option specifies the directory where output files are written. If outdir is not passed to the JavaScript API, Bun does not write bundled code to disk and returns the bundled files in an array of BuildArtifact objects. When outdir is set, the path property on a BuildArtifact is the absolute path it was written to.
Bun.build() basic API signature
The Bun.build() JavaScript API accepts an options object with entrypoints and outdir: await Bun.build({ entrypoints: ['./index.tsx'], outdir: './build' }). It returns a Promise<BuildOutput>.
entrypoints option is required
The entrypoints option is required. It accepts an array of paths corresponding to the entrypoints of the application. Bun generates one bundle per entrypoint.
files option for in-memory bundling
The files option is only available in the JavaScript API and allows bundling virtual files that don't exist on disk, or override the contents of files that do. File contents can be provided as a string, Blob, TypedArray, or ArrayBuffer. In-memory files take priority over files on disk.
BuildOutput interface returned from Bun.build()
Bun.build() returns Promise<BuildOutput> with structure: { outputs: BuildArtifact[], success: boolean, logs: Array<BuildMessage | ResolveMessage>, metafile?: BuildMetafile }
BuildArtifact extends Blob interface
BuildArtifact extends the Blob interface and includes: kind ('entry-point' | 'chunk' | 'asset' | 'sourcemap' | 'bytecode'), path (absolute file path), loader (Loader type), hash (content hash or null), sourcemap (associated BuildArtifact or null)
BuildArtifact Blob methods
BuildArtifact objects can be consumed as Blobs using: arrayBuffer(), bytes() (returns Uint8Array), text() (returns string).
BuildArtifact can be passed to Response constructor
BuildArtifact objects can be passed directly into new Response(). The Content-Type header is automatically set based on the artifact type.
BuildMessage error class structure
BuildMessage has properties: name (string), position (Position | undefined), message (string), level ('error' | 'warning' | 'info' | 'debug' | 'verbose')
ResolveMessage extends BuildMessage
ResolveMessage extends BuildMessage and adds: code (string), referrer (string), specifier (string), importKind ('entry_point' | 'stmt' | 'require' | 'import' | 'dynamic' | 'require_resolve' | 'at' | 'at_conditional' | 'url' | 'internal')
Full BuildConfig TypeScript interface definition
BuildConfig interface contains: entrypoints (required, string[]), outdir? (string), target? (Target, default browser), format? ('esm'|'cjs'|'iife', default esm), jsx? (object with runtime, importSource, factory, fragment, sideEffects, development), naming? (string or object), root? (string), splitting? (boolean, default false), plugins? (BunPlugin[]), external? (string[]), packages? ('bundle'|'external'), publicPath? (string), define? (Record<string,string>), loader? (Record<string,Loader>), sourcemap? ('none'|'linked'|'inline'|'external'|boolean, default none), conditions? (string[]|string), env? ('inline'|'disable'|`${string}*`), minify? (boolean|object), ignoreDCEAnnotations? (boolean), emitDCEAnnotations? (boolean), bytecode? (boolean), banner? (string), footer? (string), drop? (string[]), throw? (boolean, default true), tsconfig? (string)
Bun.build() JavaScript API for standalone HTML
Use Bun.build() with compile: true and target: "browser" to produce standalone HTML programmatically. Required options: entrypoints (array with HTML file path), compile: true, target: "browser". Optional options: outdir (directory for output; if omitted, output is available as BuildArtifact in result.outputs), minify (boolean to minify JS and CSS). When outdir is omitted, access the HTML via result.outputs[0].text(). Example: const result = await Bun.build({ entrypoints: ["./index.html"], compile: true, target: "browser", outdir: "./dist", minify: true }); Check result.success before accessing result.outputs and result.logs.
HTML dev server features
Bun's development server for HTML provides: automatic bundling of HTML, JavaScript, and CSS; multi-entry support for multiple HTML entry points and glob patterns; TypeScript and JSX support by default; smart configuration reading from tsconfig.json; plugin support including TailwindCSS; ESM and CommonJS support; CSS bundling and minification; asset management with copying, hashing, and path rewriting in JavaScript, CSS, and HTML.
Single Page Apps fallback route behavior
When you pass a single `.html` file to Bun, it serves that file as a fallback route for all paths. This suits single page apps that use client-side routing. Routes like `/about` and `/users/123` serve the same HTML file, allowing the client-side router to handle navigation.
Multi-page apps with multiple HTML entry points
To support multiple HTML entry points, pass them all to `bun`. For example, `bun ./index.html ./about.html` serves index.html at `/` and about.html at `/about`. You can also use glob patterns ending in `.html`, like `bun ./**/*.html`.
Path normalization for multiple HTML files
When multiple HTML files are provided, Bun chooses the base path from the longest common prefix among all the files. For example, with `./index.html ./about/index.html ./about/foo/index.html`, the routes are `/`, `/about`, and `/about/foo`.
Automatic HTML asset processing
Bun automatically handles all common web assets: `<script src>` tags are run through the JavaScript/TypeScript/JSX bundler; `<link rel="stylesheet">` tags are run through the CSS parser and bundler; `<img>` and `<picture>` tags are copied and hashed; `<video>`, `<audio>`, and `<source>` tags are copied and hashed; any `<link>` tag with an `href` attribute pointing to a local file is rewritten to the new path and hashed.
HTML bundler zero-configuration support
Bun's bundler has first-class support for HTML. Point Bun at your HTML file and it automatically bundles the scripts, stylesheets, and assets the file references with zero configuration.
HTML file path resolution
Bun resolves all paths in HTML relative to the HTML file itself, so you can organize your project however you want.