TypeScript

Overview

Bun is designed with TypeScript in mind. It natively executes TypeScript and TSX files without requiring a separate transpilation step. This makes Bun an ideal runtime for TypeScript projects.

terminal

bun run index.ts
bun run component.tsx

Bun’s transpiler only strips TypeScript syntax—it doesn’t perform type checking. Use tsc (the official TypeScript compiler) for type checking in development and CI.

Install type definitions

To install TypeScript type definitions for Bun’s built-in APIs, install @types/bun:

terminal

bun add -d @types/bun

At this point, you should be able to reference the global Bun object in your TypeScript files without seeing errors in your editor.

console.log(Bun.version);

What is @types/bun?

The @types/bun package is a shim package that re-exports types from bun-types, which lives in the Bun repository under packages/bun-types.The types include:

The global Bun namespace with all runtime APIs
Type definitions for bun:* built-in modules like bun:test, bun:sqlite, bun:ffi
Augmented types for Node.js compatibility APIs
Web API types that extend standard TypeScript lib types

Recommended `tsconfig.json`

Bun supports features like top-level await, JSX, and extensioned imports (.ts imports) that TypeScript doesn’t allow by default. Here’s a recommended tsconfig.json for Bun projects that enables these features without compilation warnings:

tsconfig.json

{
  "compilerOptions": {
    // Environment & latest features
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,

    // Bundler mode
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,

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

    // Some stricter flags (disabled by default)
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noPropertyAccessFromIndexSignature": false
  }
}

If you run bun init in a fresh directory, this tsconfig.json will be auto-generated for you.

terminal

bun init

Key compiler options explained

module: Preserve

Sets the module system to Preserve, which keeps import/export statements as-is without transforming them. This is ideal for Bun since it natively supports ESM.

moduleResolution: bundler

Uses the bundler resolution algorithm, which matches the behavior of modern bundlers and runtimes like Bun. This enables features like:

Importing TypeScript files with .ts extensions
Proper resolution of exports field in package.json
Support for extensionless imports

allowImportingTsExtensions: true

Allows importing TypeScript files with .ts and .tsx extensions:

import { foo } from "./foo.ts"; // ✅ Allowed

Without this flag, TypeScript would require you to omit the extension.

verbatimModuleSyntax: true

Ensures that import/export statements are preserved exactly as written. This helps catch errors where you might accidentally use import type syntax that would be stripped.

noEmit: true

Prevents TypeScript from generating output files. Since Bun handles transpilation at runtime, you don’t need TypeScript to emit JavaScript files.

Native TypeScript features

Bun supports several TypeScript features natively:

Top-level await

Use await at the top level of your modules:

index.ts

const response = await fetch("https://api.example.com/data");
const data = await response.json();

console.log(data);

JSX and TSX

Bun can execute .jsx and .tsx files directly:

Component.tsx

export function Welcome({ name }: { name: string }) {
  return <h1>Hello, {name}!</h1>;
}

terminal

bun run Component.tsx

Extensioned imports

Import TypeScript files with their full extensions:

import { greet } from "./greet.ts";
import { Component } from "./Component.tsx";

This is more explicit and aligns with browser-native ESM behavior.

Decorators

Bun supports experimental decorators and the TypeScript 5.0+ decorator proposal:

tsconfig.json

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Path mapping

Bun respects paths in tsconfig.json for module resolution:

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

Now you can use these path aliases:

import { Button } from "@components/Button";
import { utils } from "@/utils";

Type checking

Bun’s runtime doesn’t perform type checking—it only strips type annotations. For type checking, use the TypeScript compiler:

terminal

# Type check once
bun tsc --noEmit

# Type check in watch mode
bun tsc --noEmit --watch

Add this as a script in your package.json:

package.json

{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}

Then run:

terminal

bun run typecheck

DOM types

If you’re building a browser application and need DOM types, add "DOM" to the lib array:

tsconfig.json

{
  "compilerOptions": {
    "lib": ["ESNext", "DOM", "DOM.Iterable"]
  }
}

This enables types for document, window, HTMLElement, and other browser APIs.

Node.js types

Bun implements many Node.js APIs for compatibility. If you’re using Node.js modules, you may want to install Node.js type definitions:

terminal

bun add -d @types/node

However, be aware that @types/node can conflict with Bun’s types. Bun’s types take precedence for built-in modules.

Transpilation options

Configure how Bun transpiles TypeScript via bunfig.toml:

bunfig.toml

[runtime]
# Set the JSX factory
jsx = "react"
jsxFactory = "h"
jsxFragment = "Fragment"

# Enable TypeScript experimental decorators
experimentalDecorators = true

Alternatively, set these options in tsconfig.json and Bun will respect them:

tsconfig.json

{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "h",
    "jsxFragmentFactory": "Fragment",
    "experimentalDecorators": true
  }
}

Type stripping

Bun strips the following TypeScript syntax during transpilation:

Type annotations
Interface declarations
Type aliases
Enums (converted to JavaScript objects)
Namespace declarations (experimental)
import type and export type statements
Type-only imports/exports

Enums

TypeScript enums are converted to JavaScript objects:

enum Status {
  Pending,
  Success,
  Error,
}

Becomes:

var Status;
(function (Status) {
  Status[(Status["Pending"] = 0)] = "Pending";
  Status[(Status["Success"] = 1)] = "Success";
  Status[(Status["Error"] = 2)] = "Error";
})(Status || (Status = {}));

Editor support

VS Code

Install the Bun for Visual Studio Code extension for enhanced Bun support:

Syntax highlighting for bunfig.toml
Debug support for Bun
Run configurations for bun run, bun test, etc.

Other editors

Most editors with TypeScript support work great with Bun:

IntelliJ IDEA / WebStorm: Full TypeScript support built-in
Vim/Neovim: Use typescript-language-server or coc-tsserver
Sublime Text: Install the TypeScript plugin
Emacs: Use tide or lsp-mode with typescript-language-server

Compatibility with TypeScript versions

Bun’s transpiler targets compatibility with the latest stable TypeScript release. Bun generally supports:

✅ TypeScript 5.0+ (full support)
✅ TypeScript 4.x (full support)
⚠️ TypeScript 3.x (mostly supported, but some features may not work)

Migration from Node.js

If you’re migrating a TypeScript project from Node.js to Bun:

Install Bun types

terminal

bun add -d @types/bun

Update tsconfig.json

Use the recommended configuration above.

Remove ts-node or tsx

You no longer need these packages since Bun natively runs TypeScript:

terminal

bun remove ts-node tsx

Update scripts

Replace ts-node or tsx with bun in your package.json scripts:

package.json

{
  "scripts": {
    "start": "bun run src/index.ts", // Was: ts-node src/index.ts
    "dev": "bun --watch run src/index.ts"
  }
}

Test your application

terminal

bun run start

Performance

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

Startup time: Bun starts 4x faster than Node.js with ts-node
Transpilation: Bun’s transpiler is written in Zig and optimized for speed
No compilation step: Run .ts files directly without a build step

For production builds, consider using bun build to bundle and minify your TypeScript code.

Additional resources

Runtime TypeScript

Learn more about TypeScript support in Bun’s runtime.

Transpiler API

Use Bun’s transpiler programmatically in your code.

Bundler

Bundle TypeScript for production with Bun.build.

Testing

Write TypeScript tests with Bun’s test runner.

Get Started

TypeScript

Overview

Install type definitions

Recommended `tsconfig.json`

Key compiler options explained

Native TypeScript features

Top-level await

JSX and TSX

Extensioned imports

Decorators

Path mapping

Type checking

DOM types

Node.js types

Transpilation options

Type stripping

Enums

Editor support

VS Code

Other editors

Compatibility with TypeScript versions

Migration from Node.js

Performance

Additional resources

Runtime TypeScript

Transpiler API

Bundler

Testing

Build docs developers (and LLMs) love

Get Started

​Overview

​Install type definitions

​Recommended tsconfig.json

​Key compiler options explained

​Native TypeScript features

​Top-level await

​JSX and TSX

​Extensioned imports

​Decorators

​Path mapping

​Type checking

​DOM types

​Node.js types

​Transpilation options

​Type stripping

​Enums

​Editor support

​VS Code

​Other editors

​Compatibility with TypeScript versions

​Migration from Node.js

​Performance

​Additional resources

Runtime TypeScript

Transpiler API

Bundler

Testing

Build docs developers (and LLMs) love

Overview

Install type definitions

Recommended `tsconfig.json`

Key compiler options explained

Native TypeScript features

Top-level await

JSX and TSX

Extensioned imports

Decorators

Path mapping

Type checking

DOM types

Node.js types

Transpilation options

Type stripping

Enums

Editor support

VS Code

Other editors

Compatibility with TypeScript versions

Migration from Node.js

Performance

Additional resources