Skip to main content
Bun is an all-in-one JavaScript runtime built from scratch for speed. It natively executes JavaScript, TypeScript, JSX, and TSX files without requiring external transpilers.

​
Key Features

Native TypeScript

Execute .ts and .tsx files directly without compilation

JSX Support

Built-in JSX/TSX transpilation with React & custom factory support

Fast Transpilation

Zig-powered transpiler with automatic hot reloading

ESM & CommonJS

Seamless interoperability between module systems

​
Quick Start

Run any JavaScript, TypeScript, JSX, or TSX file: 
bun run index.ts
bun run app.tsx
bun run server.js
Bun automatically detects the file type and applies the appropriate loader.

​
Architecture

Bun’s runtime is built on several core components:

​
Transpiler

The transpiler (src/transpiler.zig) converts TypeScript and JSX to JavaScript on-the-fly:
  • TypeScript stripping: Removes type annotations while preserving runtime behavior
  • JSX transformation: Converts JSX syntax to function calls
  • Modern syntax: Supports decorators, using declarations, and latest TC39 proposals
  • Source maps: Generates accurate source maps for debugging

​
Module Loader

Bun’s module resolution follows Node.js conventions with enhancements:
  • Package.json resolution: Respects exports, main, module fields
  • Extension handling: Auto-resolves .ts, .tsx, .jsx extensions
  • Path mapping: Supports tsconfig.json paths and baseUrl
  • Virtual modules: Built-in modules like bun:ffi, bun:sqlite

​
Runtime Features

Automatic .env file loading with multiple environment support:
  • .env - Base configuration
  • .env.local - Local overrides (gitignored)
  • .env.production - Production-specific
  • .env.development - Development-specific
Built-in file watcher for automatic reloading:
  • Cross-platform implementation (kqueue on macOS, inotify on Linux)
  • Smart debouncing to avoid excessive reloads
  • Configurable watch patterns
React Fast Refresh and custom HMR support:
  • Preserves component state during updates
  • Automatic boundary detection
  • Framework-agnostic HMR API

​
Performance

Bun’s runtime achieves exceptional performance through:
  • JavaScriptCore engine: Apple’s optimized JS engine from WebKit
  • Zig implementation: Zero-cost abstractions and manual memory management
  • Lazy transpilation: Only transpiles files when imported
  • Runtime transpiler cache: Caches transpiled code with hash-based invalidation
  • Inline syscalls: Direct system calls without libc overhead

​
Configuration

Configure runtime behavior with bunfig.toml:
Runtime configuration
# Automatically load environment variables
[env]
file = [".env", ".env.local"]

# Preload scripts before execution
preload = ["./setup.ts"]

# Set log level
logLevel = "debug"
See bunfig.toml documentation for all options.

​
Runtime APIs

Bun extends JavaScript with runtime-specific APIs:
Runtime APIs
// Fast file operations
const file = Bun.file("./data.json");
const text = await file.text();

// Native TCP/HTTP server
Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

// Foreign Function Interface
import { dlopen, FFIType } from "bun:ffi";

const lib = dlopen("libsqlite3.so", {
  sqlite3_libversion: {
    returns: FFIType.cstring,
    args: [],
  },
});

​
Next Steps

Loaders

Learn about file type loaders and transpilation

TypeScript

TypeScript support and configuration

JSX

JSX/TSX transformation options

Environment Variables

Managing environment configuration

​
Source Code

Explore the runtime implementation:
  • Runtime core: src/runtime.zig - Runtime initialization and features
  • Transpiler: src/transpiler.zig - TypeScript/JSX transpilation
  • JS Parser: src/js_parser.zig - JavaScript AST parser
  • Module loader: src/bun.js/module_loader/ - Module resolution
  • Environment loader: src/env_loader.zig - .env file parsing

Build docs developers (and LLMs) love

Get started for freeTalk to us