Bun Runtime

Bun Runtime

Bun is a fast all-in-one JavaScript runtime built on JavaScriptCore (Safari's engine). It provides 4x faster startup than Node.js on Linux.

Quick Start

# Run a file
bun run index.ts
bun index.ts  # shorthand

# Run with watch mode
bun --watch run index.ts

# Run package.json script
bun run dev

# Run with hot reloading
bun --hot run server.ts

Core CLI Flags

Running Files

Bun transpiles TypeScript and JSX on-the-fly:

bun run index.js
bun run index.ts
bun run index.jsx
bun run index.tsx

Important: Put Bun flags immediately after bun:

bun --watch run dev    # Correct
bun run dev --watch    # Wrong - flag passed to script

Package.json Scripts

# Run script
bun run dev
bun dev  # shorthand (if no Bun command conflicts)

# List available scripts
bun run

# Run with Bun instead of Node
bun run --bun vite

Bun respects lifecycle hooks (preclean, postclean, etc.).

Watch Mode vs Hot Reloading

# Watch mode - full restart
bun --watch run server.ts

# Hot reloading - preserves connections/state
bun --hot run server.ts

Environment Variables

Bun automatically loads .env files:

# Loads automatically: .env, .env.local, .env.development
bun run index.ts

# Specify env file
bun --env-file .env.production run index.ts

# Disable auto-loading
# In bunfig.toml: env = false

Access in code:

const apiKey = process.env.API_KEY;
const bunEnv = Bun.env.NODE_ENV;

Globals Available

Preload Scripts

Load modules before your main script:

bun --preload ./setup.ts run index.ts

Or in bunfig.toml:

preload = ["./setup.ts"]

Use cases: polyfills, global setup, instrumentation.

Stdin Execution

# Pipe code to Bun
echo "console.log('Hello')" | bun run -

# Redirect file
bun run - < script.js

Workspaces & Monorepos

# Run script in specific packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

Debugging

# Start debugger
bun --inspect run index.ts

# Wait for debugger connection
bun --inspect-wait run index.ts

# Break on first line
bun --inspect-brk run index.ts

Connect via Chrome DevTools or VS Code.

Common Errors

When to Load References

Load references/bunfig.md when:

• Configuring bunfig.toml
• Setting up test configuration
• Configuring package manager behavior
• Setting JSX options

Load references/cli-flags.md when:

• Need complete CLI flag reference
• Configuring advanced runtime options
• Setting up debugging

Load references/module-resolution.md when:

• Troubleshooting import errors
• Configuring path aliases
• Understanding Bun's resolution algorithm

bunfig.toml Configuration Reference

Complete reference for configuring Bun's behavior via bunfig.toml.

File Locations

Local (project root): bunfig.toml Global: $HOME/.bunfig.toml or $XDG_CONFIG_HOME/.bunfig.toml

Local settings override global. CLI flags override both.

Runtime Configuration

preload

Load scripts/plugins before running files:

preload = ["./preload.ts"]

jsx

Configure JSX handling (also settable in tsconfig.json):

jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"
jsxImportSource = "react"

smol

Reduce memory usage at cost of performance:

smol = true

logLevel

Set log verbosity:

logLevel = "debug"  # "debug" | "warn" | "error"

define

Replace global identifiers with constant expressions:

[define]
"process.env.bagel" = "'lox'"

loader

Map file extensions to loaders:

[loader]
".bagel" = "tsx"

Available loaders: jsx, js, ts, tsx, json, jsonc, toml, yaml, css, html, text, wasm, napi, file, sh

telemetry

Enable/disable analytics and crash reports:

telemetry = false

env

Configure .env file loading:

# Disable automatic .env loading
env = false

# Or use object syntax
[env]
file = false

console

Configure console output:

[console]
depth = 3  # Default: 2

Test Runner Configuration

[test]
root = "./__tests__"
preload = ["./setup.ts"]
smol = true
coverage = true
coverageThreshold = 0.9
coverageSkipTestFiles = false
coveragePathIgnorePatterns = ["**/*.spec.ts", "**/*.test.ts"]
coverageReporter = ["text", "lcov"]
coverageDir = "coverage"
randomize = true
seed = 2444615283
rerunEach = 3
concurrentTestGlob = "**/concurrent-*.test.ts"
onlyFailures = true

[test.reporter]
dots = true
junit = "test-results.xml"

Coverage Threshold Options

# Single threshold for all
coverageThreshold = 0.9

# Per-type thresholds
coverageThreshold = { line = 0.7, function = 0.8, statement = 0.9 }

Package Manager Configuration

[install]
optional = true              # Install optionalDependencies
dev = true                   # Install devDependencies
peer = true                  # Install peerDependencies
production = false           # Production mode
exact = false                # Use exact versions in package.json
saveTextLockfile = true      # Use text-based bun.lock
auto = "auto"                # Auto-install behavior
frozenLockfile = false       # Don't update lockfile
dryRun = false               # Don't actually install
globalDir = "~/.bun/install/global"
globalBinDir = "~/.bun/bin"
registry = "https://registry.npmjs.org"
linkWorkspacePackages = true
linker = "hoisted"           # "hoisted" | "isolated"
minimumReleaseAge = 259200   # 3 days in seconds
minimumReleaseAgeExcludes = ["@types/bun", "typescript"]

Auto-install Values

Scoped Registries

[install.scopes]
myorg = "https://username:password@registry.myorg.com/"
myorg = { username = "myusername", password = "$npm_password", url = "https://registry.myorg.com/" }
myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }

Cache Configuration

[install.cache]
dir = "~/.bun/install/cache"
disable = false
disableManifest = false

Lockfile Configuration

[install.lockfile]
save = true
print = "yarn"  # Generate yarn.lock alongside bun.lock

Security Scanner

[install.security]
scanner = "@acme/bun-security-scanner"

CA Certificates

[install]
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
cafile = "path/to/cafile"

bun run Configuration

[run]
shell = "system"  # "system" | "bun"
bun = true        # Auto-alias node to bun
silent = true     # Suppress command output

Debug Configuration

[debug]
editor = "code"  # Editor for blob:/src: links

Available editors: subl, sublime, vscode, code, textmate, mate, idea, webstorm, nvim, neovim, vim, vi, emacs

Complete Example

# Runtime
preload = ["./setup.ts"]
smol = false
logLevel = "warn"
telemetry = false

[define]
"process.env.NODE_ENV" = "'production'"

[loader]
".graphql" = "text"

[console]
depth = 4

# Testing
[test]
root = "./tests"
coverage = true
coverageThreshold = { line = 0.8, function = 0.9 }
coverageReporter = ["text", "lcov"]

# Package Manager
[install]
production = false
exact = false
saveTextLockfile = true
linker = "isolated"

[install.scopes]
company = { token = "$NPM_TOKEN", url = "https://npm.company.com/" }

# bun run
[run]
shell = "bun"
bun = true
silent = false

Bun CLI Flags Reference

Complete reference for bun run CLI flags and options.

General Execution

Workspace Management

Runtime & Process Control

Development Workflow

Debugging

Dependency & Module Resolution

Transpilation & Language

Networking & Security

Global Configuration

Examples

Basic Execution

# Run a file
bun run index.ts
bun index.ts  # shorthand

# Run package.json script
bun run dev
bun dev  # shorthand

# Run with flags
bun --watch run index.ts
bun --hot run server.ts

Watch & Development

# Watch mode (full restart)
bun --watch run server.ts

# Hot reloading (preserves state)
bun --hot run server.ts

# With verbose output
bun --watch --no-clear-screen run dev

Debugging

# Start debugger
bun --inspect run index.ts

# Wait for debugger
bun --inspect-wait run index.ts

# Break on first line
bun --inspect-brk run index.ts

Workspaces

# Run in matching packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

# Exclude packages
bun install --filter '!pkg-c'

Environment

# Specific env file
bun --env-file .env.production run index.ts

# Multiple env files
bun --env-file .env --env-file .env.local run index.ts

Memory & Performance

# Reduce memory usage
bun --smol run index.ts

# Increase console depth
bun --console-depth 5 run index.ts

Forcing Bun Runtime

# Force Bun instead of Node for CLI tools
bun --bun run vite
bun run --bun next dev

Piping Code

# Execute from stdin
echo "console.log('Hello')" | bun run -

# Redirect file
bun run - < script.js

Custom Loaders

# Custom file extension loader
bun --loader .graphql:text run index.ts

# Multiple loaders
bun -l .sql:text -l .md:text run index.ts

Define Constants

# Replace at parse time
bun --define process.env.NODE_ENV:"'production'" run build.ts
bun -d DEBUG:true run index.ts

Drop Code

# Remove console calls
bun --drop=console run index.ts

# Remove debugger statements
bun --drop=debugger run index.ts

Bun Module Resolution Reference

How Bun resolves modules and handles imports in JavaScript and TypeScript.

Import Syntax

Extension Resolution Order

When importing without extension, Bun checks in order:

./hello.tsx
./hello.jsx
./hello.ts
./hello.mjs
./hello.js
./hello.cjs
./hello.json
./hello/index.tsx
./hello/index.jsx
./hello/index.ts
./hello/index.mjs
./hello/index.js
./hello/index.cjs
./hello/index.json

With Extensions

import { hello } from "./hello";      // Extensionless
import { hello } from "./hello.ts";   // TypeScript
import { hello } from "./hello.js";   // Also resolves .ts/.tsx

Importing from .js also checks for matching .ts file (TypeScript compatibility).

Module Systems

Bun supports both ES Modules and CommonJS.

Module Type Resolution

Using require()

const { foo } = require("./foo");      // No extension
const { bar } = require("./bar.mjs");  // ESM
const { baz } = require("./baz.tsx");  // TSX

Using import

import { foo } from "./foo";
import bar from "./bar.ts";
import { stuff } from "./my-commonjs.cjs";

Mixed Usage

// Both work in same file
import { stuff } from "./my-commonjs.cjs";
const myStuff = require("./my-commonjs.cjs");

Top-Level Await Restriction

Files with top-level await cannot be require()d (synchronous limitation). Use import or dynamic import() instead.

Package Resolution

exports Field Priority

{
  "name": "foo",
  "exports": {
    "bun": "./index.ts",     // Bun-specific (TypeScript!)
    "node": "./index.js",    // Node.js
    "require": "./index.js", // CommonJS
    "import": "./index.mjs", // ESM
    "default": "./index.js"  // Fallback
  }
}

First matching condition wins.

Subpath Exports

{
  "exports": {
    ".": "./index.js",
    "./utils": "./utils.js"
  }
}

Conditional Subpath Exports

{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}

Fallback Fields

If no exports, Bun checks: 1. module (ESM imports only) 2. main

{
  "name": "foo",
  "module": "./index.mjs",
  "main": "./index.js"
}

Shipping TypeScript

Use "bun" export condition for direct TypeScript:

{
  "exports": {
    "bun": "./src/index.ts",
    "default": "./dist/index.js"
  }
}

Custom Conditions

bun build --conditions="react-server" --target=bun ./app.js
bun --conditions="react-server" ./app.js

Programmatic:

await Bun.build({
  conditions: ["react-server"],
  target: "bun",
  entryPoints: ["./app.js"],
});

Path Re-mapping

tsconfig.json paths

{
  "compilerOptions": {
    "paths": {
      "config": ["./config.ts"],
      "components/*": ["components/*"]
    }
  }
}

package.json imports (Node.js style)

{
  "imports": {
    "#config": "./config.ts",
    "#components/*": "./components/*"
  }
}

NODE_PATH

Additional module resolution directories:

NODE_PATH=./packages bun run src/index.js

# Multiple paths
NODE_PATH=./packages:./lib bun run src/index.js  # Unix
NODE_PATH=./packages;./lib bun run src/index.js  # Windows

import.meta Properties

Usage Examples

// Get current directory (like __dirname)
const dir = import.meta.dir;

// Check if main entry point
if (import.meta.main) {
  console.log("Running directly");
}

// Resolve module path
const zodPath = import.meta.resolve("zod");
// "file:///path/to/node_modules/zod/index.js"

Resolution Order

When running bun run:

1. package.json scripts 2. Source files 3. Binaries from project packages 4. System commands (bun run only)

Common Patterns

Dynamic Imports

const module = await import("./dynamic.ts");

Conditional Imports

const db = process.env.USE_SQLITE
  ? await import("./sqlite.ts")
  : await import("./postgres.ts");

JSON Imports

import config from "./config.json";
import data from "./data.json" with { type: "json" };

TOML Imports

import config from "./config.toml";

Text/File Imports

// With custom loader
import sql from "./query.sql" with { type: "text" };

Troubleshooting

Cannot find module

1. Check file exists at expected path 2. Verify extension resolution order 3. Check package.json exports field 4. Run bun install

Circular Dependencies

Bun handles circular imports, but use caution with:

• Top-level await in circular chains
• CommonJS modules with complex circular refs

TypeScript Path Aliases Not Working

Ensure tsconfig.json is at project root or specify:

bun --tsconfig-override ./path/to/tsconfig.json run index.ts