Transpiler and Bundler APIs

Relevant source files

• packages/bun-types/bun.d.ts
• src/StandaloneModuleGraph.zig
• src/ast/P.zig
• src/bake/DevServer/DirectoryWatchStore.zig
• src/bun.js/api.zig
• src/bun.js/api/BunObject.zig
• src/bun.js/api/JSBundler.zig
• src/bun.js/bindings/BunObject+exports.h
• src/bun.js/bindings/BunObject.cpp
• src/bundler/LinkerContext.zig
• src/bundler/ParseTask.zig
• src/bundler/bundle_v2.zig
• src/bundler/linker_context/scanImportsAndExports.zig
• src/cli.zig
• src/cli/Arguments.zig
• src/cli/build_command.zig
• src/defines.zig
• src/js/builtins/shell.ts
• src/js_lexer.zig
• src/js_parser.zig
• src/js_printer.zig
• src/options.zig
• src/runtime.zig
• src/shell/braces.zig
• src/shell/interpreter.zig
• src/shell/shell.zig
• test/bundler/bundler_cjs2esm.test.ts
• test/bundler/bundler_edgecase.test.ts
• test/bundler/bundler_minify.test.ts
• test/bundler/bundler_npm.test.ts
• test/bundler/bundler_plugin.test.ts
• test/bundler/bundler_string.test.ts
• test/bundler/esbuild/dce.test.ts
• test/bundler/esbuild/default.test.ts
• test/bundler/esbuild/importstar.test.ts
• test/bundler/esbuild/loader.test.ts
• test/bundler/esbuild/packagejson.test.ts
• test/bundler/esbuild/splitting.test.ts
• test/bundler/esbuild/ts.test.ts
• test/bundler/expectBundled.md
• test/bundler/expectBundled.ts
• test/bundler/run-single-bundler-test.sh
• test/js/bun/shell/bunshell.test.ts
• test/js/bun/shell/commands/mv.test.ts
• test/js/bun/shell/commands/rm.test.ts
• test/js/bun/shell/leak.test.ts
• test/js/bun/shell/lex.test.ts
• test/js/bun/shell/parse.test.ts
• test/js/bun/shell/test_builder.ts
• test/js/bun/shell/util.ts
• test/regression/issue/26460.test.ts

This page documents the programmatic JavaScript APIs for Bun's transpiler and bundler. These APIs allow JavaScript code to perform code transformation, bundling, and module analysis operations. For runtime module loading and resolution, see Module System and Resolution. For CLI bundling, see Build Command and Compilation.

Overview

Bun exposes two primary APIs for code transformation:

1. Bun.build() - A comprehensive bundler API that processes multiple entry points, performs tree-shaking, code-splitting, and outputs optimized bundles
2. Bun.Transpiler - A lower-level transpiler API for transforming individual files without bundling

Both APIs share the same underlying parser and printer infrastructure but differ in scope and capabilities.

Sources: src/bun.js/api/JSBundler.zig1-264 packages/bun-types/bun.d.ts1274-1743

Bun.build() Architecture

Figure 1: Bun.build() execution pipeline

Sources: src/bun.js/api/JSBundler.zig266-698 src/bundler/bundle_v2.zig107-157

Configuration Options

The Bun.build() function accepts a BuildConfig object with the following structure:

Figure 2: BuildConfig structure

Key configuration parsing occurs in parseConfig():

Option	Type	Parsed In	Description
entrypoints	string[]	JSBundler.zig294-366	Entry points for bundling
target	'browser'|'node'|'bun'	JSBundler.zig368-389	Runtime target environment
outdir	string	JSBundler.zig391-411	Output directory path
format	'esm'|'cjs'|'iife'	JSBundler.zig413-440	Module format
splitting	boolean	JSBundler.zig442-453	Enable code splitting
plugins	BunPlugin[]	JSBundler.zig455-474	Custom plugins
minify	boolean|object	JSBundler.zig476-517	Minification options
sourcemap	string	JSBundler.zig519-540	Source map mode
external	string[]	JSBundler.zig542-563	External modules

Sources: src/bun.js/api/JSBundler.zig266-698 packages/bun-types/bun.d.ts1274-1554

Build Output

The Bun.build() function returns a Promise<BuildOutput>:

The output construction occurs in OutputFileListBuilder:

1. Entry Point Chunks - Main entry point outputs with their module ID as hash
2. Code Split Chunks - Shared code chunks with content-based hash
3. Assets - Static files (images, fonts, etc.) with content hash
4. Source Maps - Optional .map files linked to code outputs

Sources: src/bundler/bundle_v2.zig534-855 packages/bun-types/bun.d.ts1395-1452

In-Memory Bundling with FileMap

The files option enables bundling without filesystem access:

Figure 3: FileMap resolution flow

The FileMap provides virtual filesystem capabilities:

• Cross-platform paths: Normalizes Windows backslashes to forward slashes for consistent lookup
• Relative resolution: Supports relative imports by joining with source directory
• Zero-copy reading: Direct access to in-memory buffers

Sources: src/bun.js/api/JSBundler.zig8-164 src/bundler/bundle_v2.zig121-124

Bun.Transpiler API

The Bun.Transpiler class provides lower-level file transformation:

Figure 4: Transpiler API flow

Constructor Options

The transpiler is initialized as a lazy property on the Bun global object and configures the underlying parser/printer without bundler-specific features like tree-shaking across modules.

Sources: packages/bun-types/bun.d.ts1556-1743 src/bun.js/api/BunObject.zig70

Transform Methods

Method	Async	Returns	Description
transform(code, loader?)	Yes	Promise<string>	Transform code asynchronously
transformSync(code, loader?)	No	string	Transform code synchronously
scan(code)	No	ScanResult	Extract imports/exports without transformation
scanImports(code)	No	ScannedImport[]	Extract only imports

The ScanResult interface provides module metadata:

Sources: packages/bun-types/bun.d.ts1622-1743

Plugin System

Both Bun.build() and Bun.Transpiler support plugins with lifecycle hooks:

Figure 5: Plugin execution model

Plugin Hook Types

The plugin system uses two hook types defined in BunPlugin:

onResolve Hook:

onLoad Hook:

Sources: packages/bun-types/bun.d.ts743-983 src/bun.js/api/JSBundler.zig700-1107

Plugin Execution Flow

Plugin hooks are executed in the bundler thread:

1. Registration: Plugins are parsed from the plugins array in config
2. Setup Phase: Each plugin's setup() function is called with a PluginBuilder instance
3. Hook Storage: onResolve and onLoad callbacks are stored with their filter patterns
4. Resolution Phase: For each import, matching onResolve hooks execute in registration order
5. Load Phase: For each resolved path, matching onLoad hooks execute
6. Async Handling: Plugin callbacks can return promises, which are awaited on the JS event loop

The plugin system integrates with the bundler at two key points:

• Resolution: src/bun.js/api/JSBundler.zig1109-1341 - Plugins can override module resolution
• Loading: src/bun.js/api/JSBundler.zig1343-1562 - Plugins can provide custom file contents

Sources: src/bun.js/api/JSBundler.zig700-1562

Implementation Architecture

Figure 6: Full implementation stack

Key Components

Component	File	Responsibility
JSBundler	JSBundler.zig1-264	JavaScript API entry point, config parsing
BundleV2	bundle_v2.zig107-533	Main bundler orchestration
Graph	bundle_v2.zig857-1394	Dependency graph construction
Transpiler	options.zig1-900	Configuration and options
js_parser	js_parser.zig1-1000	Parse source to AST
js_printer	js_printer.zig1-1000	Generate code from AST
LinkerContext	LinkerContext.zig1-500	Tree-shaking and linking
Plugin	JSBundler.zig700-1562	Plugin hook execution

Sources: src/bun.js/api/JSBundler.zig1-264 src/bundler/bundle_v2.zig107-533 src/js_parser.zig1-1000 src/js_printer.zig1-1000

Thread Model

The bundler uses multiple threads for performance:

1. JS Thread: Runs JavaScript code, plugin callbacks, and event loop
2. Bundle Thread: Executes parsing, resolution, and linking
3. Parse Workers: Pool of threads for parallel file parsing
4. WorkPool: Generic worker pool for CPU-intensive tasks

Communication between threads uses:

• JSBundleCompletionTask - Delivers results back to JS thread
• PollableRef - Allows JS thread to wait for bundler completion
• Plugin hooks execute on JS thread via EventLoop.enqueueTaskConcurrent()

Sources: src/bundler/bundle_v2.zig464-482 src/bun.js/api/JSBundler.zig1726-1879

Compile Mode

When compile: true is set, the bundler produces standalone executables:

Figure 7: Compile mode process

The StandaloneModuleGraph format stores:

• Serialized AST nodes for all modules
• Import/export metadata
• Virtual filesystem paths (using /$bunfs/ prefix)
• Entry point information

At runtime, the compiled executable bypasses normal file I/O and uses the embedded module graph directly.

Sources: src/StandaloneModuleGraph.zig1-100 src/cli/build_command.zig100-200