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

# TypeScript

> Bun executes TypeScript natively without a separate compilation step. No build tool or tsconfig required to get started.

Bun's runtime includes a built-in TypeScript transpiler. When you run a `.ts` or `.tsx` file, Bun strips the types on the fly and executes the resulting JavaScript — all in the same process, with no intermediate files written to disk.

```bash theme={null}
bun run index.ts      # works, no tsc or ts-node needed
bun run index.tsx     # JSX is supported too
```

<Note>
  Bun transpiles TypeScript but does **not** type-check it. Type errors in your editor will not prevent execution. Use `bunx tsc --noEmit` (see below) to run type checking separately.
</Note>

## Install type definitions

To get `Bun.*` globals and module types in your editor, install the `@types/bun` package:

```bash theme={null}
bun add -d @types/bun
```

After this, you can reference `Bun.serve`, `Bun.file`, and all other Bun APIs in TypeScript without seeing "Cannot find name 'Bun'" errors.

If you initialized your project with `bun init`, `@types/bun` is already installed and configured.

## Recommended tsconfig.json

Bun supports features that TypeScript's default settings don't allow — top-level await, importing `.ts` files by extension, and more. The following `tsconfig.json` is recommended for Bun projects:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    // Environment setup
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,
    "types": ["bun"],

    // Bundler mode (matches how Bun resolves modules)
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,

    // Best practices
    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}
```

`bun init` generates this file automatically. The key settings are:

| Setting                              | Why                                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `"module": "Preserve"`               | Tells TypeScript not to transform import/export syntax, since Bun handles that.       |
| `"moduleResolution": "bundler"`      | Matches Bun's resolution algorithm, which allows importing `.ts` files directly.      |
| `"allowImportingTsExtensions": true` | Lets you write `import { foo } from "./foo.ts"` without TypeScript complaining.       |
| `"verbatimModuleSyntax": true`       | Ensures `import type` is used for type-only imports, which is required with `noEmit`. |
| `"noEmit": true`                     | Bun handles execution; TypeScript should only be used for type checking.              |
| `"types": ["bun"]`                   | Loads Bun's global type declarations from `@types/bun`.                               |

## Type checking

Bun does not type-check your code at runtime. To catch type errors, run the TypeScript compiler in check-only mode using `bunx`:

```bash theme={null}
bunx tsc --noEmit
```

`bunx` downloads and runs `typescript` from npm without permanently installing it. If you already have TypeScript installed as a dev dependency, you can use it directly:

```bash theme={null}
bun run tsc --noEmit
```

You can add this as a `package.json` script and run it in CI:

```json package.json theme={null}
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}
```

```bash theme={null}
bun run typecheck
```

## Path aliases

Bun reads `paths` from your `tsconfig.json` and uses them for module resolution. This means path aliases you configure for TypeScript also work at runtime — no separate bundler config needed.

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

With this config, the following import resolves to `src/utils/format.ts` at runtime:

```typescript theme={null}
import { formatDate } from "@utils/format";
```

## JSX

Bun supports `.jsx` and `.tsx` files out of the box using the same transpiler. The JSX transform is controlled by the `"jsx"` field in `tsconfig.json`.

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "jsx": "react-jsx"  // uses the automatic runtime (React 17+)
  }
}
```

To use a different JSX runtime (such as Preact or Solid), set `"jsxImportSource"`:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}
```

No Babel or other transform tools are required. Bun handles all of this natively.

## TypeScript 6 and later

TypeScript 6.0 changed how `@types/*` packages are loaded. If you are using TypeScript 6.0 or later, explicitly include `"types": ["bun"]` in your `compilerOptions` to ensure Bun's global declarations are loaded:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "types": ["bun"]
  }
}
```