> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime Overview

> Bun's JavaScript runtime - fast, native TypeScript & JSX support

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

<CardGroup cols={2}>
  <Card title="Native TypeScript" icon="typescript">
    Execute `.ts` and `.tsx` files directly without compilation
  </Card>

  <Card title="JSX Support" icon="react">
    Built-in JSX/TSX transpilation with React & custom factory support
  </Card>

  <Card title="Fast Transpilation" icon="bolt">
    Zig-powered transpiler with automatic hot reloading
  </Card>

  <Card title="ESM & CommonJS" icon="cube">
    Seamless interoperability between module systems
  </Card>
</CardGroup>

## Quick Start

Run any JavaScript, TypeScript, JSX, or TSX file:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Environment Variables">
    Automatic `.env` file loading with multiple environment support:

    * `.env` - Base configuration
    * `.env.local` - Local overrides (gitignored)
    * `.env.production` - Production-specific
    * `.env.development` - Development-specific
  </Accordion>

  <Accordion title="Watch Mode">
    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
  </Accordion>

  <Accordion title="Hot Module Reloading">
    React Fast Refresh and custom HMR support:

    * Preserves component state during updates
    * Automatic boundary detection
    * Framework-agnostic HMR API
  </Accordion>
</AccordionGroup>

## 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`:

```toml Runtime configuration theme={null}
# 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](/runtime/bunfig) for all options.

## Runtime APIs

Bun extends JavaScript with runtime-specific APIs:

```typescript Runtime APIs theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Loaders" icon="file-code" href="/runtime/loaders">
    Learn about file type loaders and transpilation
  </Card>

  <Card title="TypeScript" icon="typescript" href="/runtime/typescript">
    TypeScript support and configuration
  </Card>

  <Card title="JSX" icon="react" href="/runtime/jsx">
    JSX/TSX transformation options
  </Card>

  <Card title="Environment Variables" icon="key" href="/runtime/environment-variables">
    Managing environment configuration
  </Card>
</CardGroup>

## 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