TypeScript

Using TypeScript with Bun, including type definitions and compiler options

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:

1. Install Bun types

   terminal

   bun add -d @types/bun
   
2. Update tsconfig.json

   Use the recommended configuration above.

3. Remove ts-node or tsx

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

   terminal

   bun remove ts-node tsx
   
4. 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"
     }
   }
   
5. 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.