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

# TypeScript

> Native TypeScript support in Bun without configuration

Bun natively executes TypeScript files without requiring a separate compilation step. Type annotations are stripped at runtime using Bun's fast transpiler.

## Quick Start

Run TypeScript files directly:

```bash Run TypeScript theme={null}
bun run app.ts
bun run server.mts
```

No `tsc`, no `ts-node`, no configuration needed.

## Features

<CardGroup cols={2}>
  <Card title="Zero Config" icon="bolt">
    Works out of the box without tsconfig.json
  </Card>

  <Card title="Fast Transpilation" icon="gauge-high">
    Written in Zig for maximum performance
  </Card>

  <Card title="Source Maps" icon="map">
    Accurate source maps for debugging
  </Card>

  <Card title="Path Mapping" icon="route">
    Respects tsconfig paths automatically
  </Card>
</CardGroup>

## How It Works

Bun's TypeScript transpiler:

1. **Strips type annotations** - Removes TypeScript syntax
2. **Preserves runtime behavior** - No type checking or validation
3. **Generates source maps** - Maps back to original TypeScript
4. **Caches output** - Hashes input to avoid re-transpiling

<Warning>
  Bun does **not** perform type checking. Use `tsc --noEmit` for type validation.
</Warning>

## Supported TypeScript Features

### Type Annotations

All type annotations are removed:

```typescript Type annotations theme={null}
// Types removed at runtime
function add(a: number, b: number): number {
  return a + b;
}

// Interfaces completely erased
interface User {
  id: number;
  name: string;
  email?: string;
}

// Type aliases removed
type Status = "pending" | "complete";

// Generic types erased
function identity<T>(value: T): T {
  return value;
}
```

### Enums

Enums are compiled to JavaScript objects:

```typescript Enums theme={null}
// Numeric enum
enum Direction {
  Up,
  Down,
  Left,
  Right,
}

// String enum
enum Color {
  Red = "RED",
  Green = "GREEN",
  Blue = "BLUE",
}

// Const enum (inlined)
const enum Status {
  Active = 1,
  Inactive = 0,
}
```

**Output behavior:**

* Regular enums → JavaScript objects
* Const enums → Inlined values (optimized)

### Namespaces

Namespaces are supported but discouraged (use ES modules):

```typescript Namespaces theme={null}
namespace Utils {
  export function log(msg: string) {
    console.log(msg);
  }
}

Utils.log("Hello");
```

### Decorators

Bun supports both experimental and standard decorators:

```typescript Decorators theme={null}
// Experimental decorators (legacy)
function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed
class Handler {}

// Standard decorators (TC39 Stage 3)
function log(target: any, context: ClassMethodDecoratorContext) {
  return function (this: any, ...args: any[]) {
    console.log(`Calling ${String(context.name)}`);
    return target.call(this, ...args);
  };
}

class Service {
  @log
  execute() {}
}
```

**Configuration:**

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    // For legacy decorators
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

Implementation: `src/runtime.zig:203-204`

### Using Declarations

Explicit resource management (TC39 Stage 3):

```typescript Using declarations   theme={null}
// Automatic cleanup with 'using'
using file = await openFile("data.txt");
// file.close() called automatically

// Async cleanup with 'await using'
await using db = await connectDB();
// await db.disconnect() called automatically
```

Compiles to try/finally blocks with resource disposal.

### Import/Export Extensions

Bun supports TypeScript import extensions:

```typescript Import extensions theme={null}
// Import with .ts extension
import { add } from "./math.ts";

// Import type only
import type { User } from "./types.ts";

// Import with assertion
import data from "./data.json" assert { type: "json" };
```

## tsconfig.json Support

Bun respects `tsconfig.json` configuration:

### Path Mapping

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "~/*": ["./*"]
    }
  }
}
```

```typescript Using path aliases theme={null}
import { Button } from "@components/Button";
import { config } from "@/config";
import { helper } from "~/utils/helper";
```

Implementation: `src/resolver/resolver.zig`

### Compiler Options

Bun honors these `tsconfig.json` options:

<AccordionGroup>
  <Accordion title="Module Resolution">
    * `moduleResolution` - "node", "bundler", "node16", "nodenext"
    * `baseUrl` - Base directory for module resolution
    * `paths` - Path mapping for imports
    * `types` - Type declaration packages to include
    * `typeRoots` - Directories containing type definitions
  </Accordion>

  <Accordion title="JSX Options">
    * `jsx` - "react", "react-jsx", "react-jsxdev", "preserve"
    * `jsxFactory` - JSX factory function (default: `React.createElement`)
    * `jsxFragmentFactory` - Fragment factory (default: `React.Fragment`)
    * `jsxImportSource` - Import source for automatic runtime
  </Accordion>

  <Accordion title="Transpilation">
    * `experimentalDecorators` - Enable legacy decorators
    * `emitDecoratorMetadata` - Emit design-time metadata
    * `useDefineForClassFields` - Class field initialization
    * `importsNotUsedAsValues` - Preserve/remove imports
  </Accordion>

  <Accordion title="Module Interop">
    * `esModuleInterop` - Enable default import interop
    * `allowSyntheticDefaultImports` - Allow default imports from CommonJS
    * `resolveJsonModule` - Allow importing .json files
  </Accordion>
</AccordionGroup>

<Note>
  Bun ignores type-checking options (`strict`, `noImplicitAny`, etc.) as it doesn't perform type checking.
</Note>

## Runtime Transpiler Cache

Bun caches transpiled TypeScript to avoid repeated parsing:

**Cache location:**

* Linux: `~/.bun/install/cache/`
* macOS: `~/Library/Caches/Bun/`
* Windows: `%LOCALAPPDATA%\Bun\Cache\`

**Cache invalidation:**

* File content changes (hash-based)
* `tsconfig.json` modifications
* Bun version updates

Implementation: `src/runtime.zig:210` - Runtime transpiler cache

### Disable Cache

```bash Disable cache theme={null}
export BUN_RUNTIME_TRANSPILER_CACHE_PATH=0
bun run app.ts
```

## Type Checking

Bun focuses on execution, not type checking. For type validation:

### Using TypeScript Compiler

```bash Type checking theme={null}
# Check types without emitting files
bun x tsc --noEmit

# With watch mode
bun x tsc --noEmit --watch
```

### Package.json Scripts

```json package.json theme={null}
{
  "scripts": {
    "dev": "bun run src/index.ts",
    "typecheck": "tsc --noEmit",
    "check": "bun run typecheck && bun run dev"
  }
}
```

### IDE Integration

Recommended setup:

1. **VS Code** - Install TypeScript extension
2. **Configure workspace**:
   ```json .vscode/settings.json theme={null}
   {
     "typescript.tsdk": "node_modules/typescript/lib",
     "typescript.enablePromptUseWorkspaceTsdk": true
   }
   ```

## CommonJS & ESM Interop

Bun seamlessly handles TypeScript with both module systems:

### ES Modules (.ts, .mts)

```typescript ESM TypeScript theme={null}
// app.ts - ESM by default
import { readFile } from "node:fs/promises";

export async function loadData(path: string): Promise<string> {
  return await readFile(path, "utf-8");
}
```

### CommonJS (.cts)

```typescript CommonJS TypeScript theme={null}
// utils.cts - Explicit CommonJS
import fs = require("node:fs");

export = {
  readSync(path: string): string {
    return fs.readFileSync(path, "utf-8");
  },
};
```

### Type Imports

```typescript Type-only imports theme={null}
// Only imports types (removed at runtime)
import type { User, Post } from "./types";

// Import value and type separately
import { type Config, loadConfig } from "./config";
```

## Declaration Files (.d.ts)

Bun recognizes TypeScript declaration files:

```typescript Declaration files theme={null}
// types.d.ts
declare module "*.png" {
  const value: string;
  export default value;
}

declare global {
  const BUILD_ID: string;
}

// Augment existing module
declare module "bun" {
  interface Env {
    DATABASE_URL: string;
  }
}
```

## Debugging TypeScript

Bun generates source maps for accurate debugging:

### VS Code Launch Config

```json .vscode/launch.json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug TypeScript",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "bun",
      "runtimeArgs": ["run", "--inspect"],
      "program": "${workspaceFolder}/src/index.ts",
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}
```

See [Debugger documentation](/runtime/debugger) for more details.

## Performance

Bun's TypeScript transpiler is significantly faster than `tsc` or `ts-node`:

* **Written in Zig**: Native code, no JavaScript overhead
* **Parallel parsing**: Multi-threaded for large projects
* **Lazy transpilation**: Only transpiles imported files
* **Efficient caching**: Hash-based cache invalidation

**Benchmark comparison** (transpiling 10,000 TypeScript files):

| Tool    | Time   |
| ------- | ------ |
| Bun     | \~0.5s |
| esbuild | \~2s   |
| tsc     | \~15s  |
| ts-node | \~30s  |

<Note>
  Benchmarks approximate, actual performance depends on code complexity.
</Note>

## Implementation Details

TypeScript transpilation implementation:

* **Parser**: `src/js_parser.zig` - Parses TypeScript AST
* **Printer**: `src/js_printer.zig` - Generates JavaScript
* **Transpiler**: `src/transpiler.zig` - Orchestrates parsing/printing
* **Runtime features**: `src/runtime.zig:144-327` - Feature flags and configuration

## Limitations

<Warning>
  Bun's TypeScript support has some limitations:

  * No type checking (use `tsc --noEmit`)
  * No `.d.ts` generation (use `tsc --emitDeclarationOnly`)
  * Some advanced features may not work identically to `tsc`
</Warning>

## Troubleshooting

### Module Resolution Issues

```bash Check resolution theme={null}
# Debug module resolution
BUN_DEBUG_QUIET_LOGS=0 bun run app.ts 2>&1 | grep -i resolve
```

### Path Mapping Not Working

Ensure `tsconfig.json` is in the project root:

```bash theme={null}
.
├── tsconfig.json
├── package.json  
└── src/
    └── index.ts
```

## Related

* [Loaders](/runtime/loaders) - File type handling
* [JSX](/runtime/jsx) - JSX/TSX configuration
* [Modules](/runtime/modules) - Module resolution
* [Watch Mode](/runtime/watch-mode) - Auto-reload on changes