tsconfig option
The tsconfig option is available in Bun.build configuration.
build options & configuration
127 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
minify parameter flexibility in Bun.build()
In Bun.build(), minify can be a boolean or an object. When an object, it supports granular options: identifiers, syntax, and whitespace. Example: minify: { identifiers: true, syntax: true, whitespace: true }.
sourcemap values in Bun.build()
sourcemap in Bun.build() supports "none", "linked", "inline", and "external".
naming parameter in Bun.build() for entry naming
In Bun.build(), entryNames from esbuild maps to naming.entry or a top-level naming string. Uses the same templating syntax as esbuild, but you must include [ext] explicitly. Example: naming: { entry: "[name].[ext]" } or naming: "[name].[ext]".
naming parameter in Bun.build() for chunk naming
In Bun.build(), chunkNames from esbuild maps to naming.chunk. It uses the same templating syntax as esbuild, but you must include [ext] explicitly. Example: naming: { chunk: "[name].[ext]" }.
root parameter in Bun.build() replaces outbase
In Bun.build(), outbase from esbuild is renamed to root.
write option behavior
The write option is set to true if outdir or outfile is set, otherwise it defaults to false.
naming parameter in Bun.build() for asset naming
In Bun.build(), assetNames from esbuild maps to naming.asset. It uses the same templating syntax as esbuild, but you must include [ext] explicitly. Example: naming: { asset: "[name].[ext]" }.
treeShaking option default
The treeShaking option defaults to true.
minify.keepNames maps from keepNames
In Bun.build(), keepNames from esbuild maps to minify.keepNames.
naming parameter object structure in Bun.build()
Bun.build() supports a naming key that can either be a string (equivalent to entryNames) or an object with granular options for entry, asset, and chunk. Example: naming: { entry: "[name].[ext]", asset: "[name].[ext]", chunk: "[name].[ext]" }.
ignoreDCEAnnotations replaces ignoreAnnotations
In Bun.build() JavaScript API, ignoreAnnotations from esbuild is renamed to ignoreDCEAnnotations.
jsx parameter structure in Bun.build()
In Bun.build(), JSX options are grouped under jsx: { runtime, development, factory, fragment, importSource, sideEffects }. This maps to esbuild's separate jsx, jsxDev, jsxFactory, jsxFragment, jsxImportSource, and jsxSideEffects parameters.
jsx.runtime supported values in Bun.build()
jsx.runtime in Bun.build() supports "automatic" and "classic".
Minification option for standalone executables
Enable minification with --minify flag or minify: true in Bun.build(). Granular control is available with minify: { whitespace: true, syntax: true, identifiers: true }.
--define flag injects build-time constants
The --define flag injects build-time constants into the executable, such as version numbers, build timestamps, or configuration values. Constants are inlined into the binary at build time and cost nothing at runtime.
--sourcemap flag embeds compressed sourcemap
The --sourcemap argument embeds a sourcemap compressed with zstd so that errors and stacktraces point to their original locations instead of the transpiled location. Bun decompresses and resolves the sourcemap automatically when an error occurs.
--minify flag reduces transpiled output code size
The --minify argument reduces the size of the transpiled output code. For large applications, this can save megabytes of space.
JavaScript API for define option
await Bun.build({ entrypoints: ["./src/cli.ts"], compile: { outfile: "./mycli" }, define: { BUILD_VERSION: JSON.stringify("1.2.3"), BUILD_TIME: JSON.stringify("2024-01-15T10:30:00Z") } });
CLI syntax for --define
bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
Code splitting chunk naming
Generated chunks include a content hash by default to avoid collisions. The bun build CLI names chunks like entry-a-t268ez5g.js. The naming can be customized with the naming option.
Code splitting enabled with splitting option
When splitting: 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. By default, splitting is false.
JSX automatic runtime configuration
Automatic JSX runtime uses importSource option. Example: jsx: { importSource: 'preact', runtime: 'automatic' }
JSX classic runtime configuration
Classic JSX runtime uses factory and fragment options. Example: jsx: { factory: 'h', fragment: 'Fragment', runtime: 'classic' }
feature type safety via Registry interface
To get autocomplete and catch typos at compile time for feature(), augment the Registry interface in a .d.ts file: declare module 'bun:bundle' { interface Registry { features: 'DEBUG' | 'PREMIUM' | 'BETA_FEATURES'; } }. Ensure the file is included in tsconfig.json.
Default shebang sets target to bun
If any entrypoint contains a Bun shebang (#!/usr/bin/env bun), the bundler defaults to target: 'bun' instead of 'browser'.
optimizeImports automatic mode via sideEffects
Packages with 'sideEffects': false in their package.json get barrel optimization automatically without needing explicit optimizeImports config. Use optimizeImports for packages that don't have this field.
metafile option formats: boolean, string, object
In the JavaScript API, metafile accepts: boolean (include in result object), string (write JSON to specific path), or object { json: './path.json', markdown: './path.md' } (specify separate paths for JSON and markdown).
BuildMetafile structure with inputs and outputs
The metafile object contains: inputs: { [path]: { bytes, imports: [{ path, kind, original?, external? }], format? } } and outputs: { [path]: { bytes, inputs: { [path]: { bytesInOutput } }, imports, exports, entryPoint?, cssBundle? } }
Chunk tree shaking behavior
When code splitting is enabled, each import() of a bundled JavaScript module becomes its own chunk. Tree shaking applies to these chunks. If every import() of a module lives in code that tree shaking removes and nothing else imports it, its chunk is not written. Setting treeShaking: false keeps every import() chunk. This differs from esbuild which emits a chunk for every reachable import().
feature() requires string literal argument
The feature() function requires a string literal argument. Dynamic values are not supported. Bun completely removes the bun:bundle import from the output.
features option enables compile-time feature flags
The features option enables compile-time feature flags for dead code elimination. Use import { feature } from 'bun:bundle' to conditionally include or exclude code paths at bundle time. Bun replaces feature() calls with true or false, and dead code is eliminated during minification.
drop option removes function calls from bundle
The drop option removes function calls from a bundle. For example, drop: ['console'] removes all console.log calls. Bun also removes the arguments to dropped calls even if they have side effects. Dropping 'debugger' removes all debugger statements.
target bun with format cjs adds @bun-cjs pragma
When you use target: 'bun' and format: 'cjs' together, the bundler adds the // @bun @bun-cjs pragma, and the CommonJS wrapper function is not compatible with Node.js.
target bun uses @bun pragma
All bundles generated with target: 'bun' are marked with a // @bun pragma, which tells the Bun runtime that there's no need to re-transpile the file before execution.
banner option adds prefix to final bundle
The banner option adds a banner to the final bundle. This can be a directive like 'use client' for React, or a comment block such as a license.
define option replaces identifiers at build time
The define option is a map of global identifiers to be replaced at build time. Keys can be identifiers or dotted property paths like 'process.env.NODE_ENV'. Values are JSON strings, identifiers, or property paths that are inlined.
publicPath prefixes import paths in bundles
The publicPath option adds a prefix to any import paths in bundled code. This applies to asset imports, external modules, and chunking. By default imports are relative; publicPath can make them absolute or URL-based.
root option specifies project root directory
The root option specifies the root directory of the project. If unspecified, Bun uses the first common ancestor of all entrypoint files as the root.
naming object with entry, chunk, asset templates
In the JavaScript API, naming can be an object: naming: { entry: '[dir]/[name].[ext]', chunk: '[name]-[hash].[ext]', asset: '[name]-[hash].[ext]' } with default values shown. CLI uses separate flags: --entry-naming, --chunk-naming, --asset-naming.
naming option applies only to entrypoints by default
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 separate template strings for entry, chunk, and asset.
naming option customizes generated file names
The naming option customizes generated file names. Defaults to '[dir]/[name].[ext]'. It accepts template tokens: [name] (entrypoint name without extension), [ext] (extension), [hash] (bundle contents hash), [dir] (relative path from project root to parent directory).
Output formats: esm, cjs, iife
The --format option specifies module format. esm is the default and supports top-level await and import.meta. cjs (CommonJS) and iife are experimental. When format is 'cjs', the default target changes from 'browser' to 'node'.
packages option controls dependency bundling
The packages option controls whether package dependencies are included in the bundle. Possible values: 'bundle' (default) or 'external'. Bun treats any import whose path does not start with '.', '..', or '/' as a package.
external option prevents bundling imports
The external option accepts a list of import paths to consider external. Defaults to []. External imports are not included in the final bundle; the bundler leaves the import statement as-is to be resolved at runtime. Use wildcard '*' to mark all imports as external.
footer option adds suffix to final bundle
The footer option adds a footer to the final bundle. This can be a comment block for a license or a fun easter egg.
minify option default and granular control
The minify option defaults to false. Set minify: true to enable all minification. For granular control, use minify: { whitespace: true, identifiers: true, syntax: true }.
sourcemap external uses debugId
With sourcemap: 'external', a separate *.js.map file is created without inserting a //# sourceMappingURL comment. Generated bundles contain a debugId that can be used to associate a bundle with its corresponding sourcemap, added as a comment at the bottom of the file. The associated *.js.map sourcemap is a JSON file containing an equivalent debugId property.
sourcemap linked requires outdir
The sourcemap: 'linked' option requires --outdir to be set. The base URL in the //# sourceMappingURL comment can be customized with --public-path.
features works across build, run, and test
Feature flags work with bun build, bun run, and bun test. Multiple flags can be enabled: --feature FLAG_A --feature FLAG_B
sourcemap generation options
The sourcemap option controls sourcemap generation with four values: 'none' (default, no sourcemap), 'linked' (separate *.js.map file with //# sourceMappingURL comment), 'external' (separate *.js.map without comment, uses debugId), 'inline' (sourcemap appended as base64).
optimizeImports skips parsing unused barrel exports
The optimizeImports option skips parsing unused submodules of barrel files (re-export index files). When you import only a few named exports from a large library, the bundler parses only the submodules you use instead of every file the barrel re-exports.
optimizeImports works with pure barrel files
optimizeImports works for pure barrel 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.
optimizeImports defers named re-exports only
The bundler always loads export * re-exports to avoid circular resolution issues. It defers only named re-exports (export { X } from './x') that no importer uses.
env option prefix matching
The env option can be set to a prefix string ending with * (e.g., 'ACME_PUBLIC_*') to inline only environment variables matching that prefix. Variables not matching the prefix remain as process.env.FOO references.
metafile option generates build metadata
The metafile option generates metadata about the build in a structured format describing every input and output file with sizes, imports, and exports. Use it for bundle analysis, visualization, dependency tracking, and CI integration.
env option inline behavior
When env: 'inline', environment variables are injected into the bundled output by converting process.env.FOO references to string literals containing the actual environment variable values.
metafile markdown output with --metafile-md
Use --metafile-md to generate a markdown metafile, which is LLM-friendly and readable in the terminal. Both --metafile and --metafile-md can be used together.
Build targets: browser, bun, node
The --target option specifies the intended execution environment. Three values are supported: browser (default, prioritizes 'browser' export condition), bun (for Bun runtime, marks bundles with // @bun pragma), and node (prioritizes 'node' export condition).
env option disable value
When env: 'disable', environment variable injection is disabled entirely.