Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Runtime Basics

TypeScript and JSX in Bun

Run TypeScript and JSX in Bun with no build step - how type stripping works, what is not checked, the recommended tsconfig.json, path aliases, enums and decorators, and JSX settings.

One of the first things people notice about Bun is that you can run a .ts or .tsx file directly. There is no tsc step, no ts-node, no Babel. Bun's native transpiler reads the file, removes the type annotations, converts JSX to function calls, and hands plain JavaScript to the engine, all in a few milliseconds. This lesson explains exactly what Bun does with TypeScript, what it leaves alone, and how to set up tsconfig.json so your editor and Bun agree.

What "running TypeScript" really means

TypeScript has two jobs: type checking and transpiling (turning .ts into .js). Bun does only the second. The transpiler strips annotations, interfaces and type aliases, and rewrites a few TypeScript-only constructs such as enum and constructor parameter properties.

TypeScript
// order.ts
interface Order {
  id: number;
  total: number;
}

const order: Order = { id: 1, total: "not a number" as unknown as number };
console.log(order.total * 2);

This runs and prints NaN. The type system never complained because Bun never asked it. That is by design: transpile-only is what makes start-up instant. For real checking, run the compiler separately:

Terminal
bunx tsc --noEmit

Add that to a check script and to CI. Editors such as VS Code do the same check live as you type.

Because Bun does not check types, a green bun run does not prove your types are correct. Always run tsc --noEmit (or an equivalent) in CI.

A Node stand-in for type stripping

Node 24 can also run TypeScript by stripping types, but only with erasable syntax. This stand-in shows the core idea: the annotations disappear and the logic runs. The first line selects TypeScript mode on the site's runner.

Node.js Stand-in: type annotations are erased at run time (Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

bun init writes a good starting file. It looks like this (comments abridged):

JSON
{
  "compilerOptions": {
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "Preserve",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "noEmit": true,

    "strict": true,
    "skipLibCheck": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  }
}

What the important lines do:

  • "module": "Preserve" and "moduleResolution": "bundler" match how Bun resolves imports, including extensionless paths and package.json exports.
  • "allowImportingTsExtensions": true lets you write import { x } from "./utils.ts", which Bun accepts.
  • "verbatimModuleSyntax": true makes type-only imports explicit (see below) so nothing surprising is left or removed.
  • "noEmit": true because Bun, not tsc, produces the JavaScript; tsc is only the checker.
  • "strict": true turns on the full set of safety checks. Keep it.

You also need the types for Bun's own globals:

Terminal
bun add -d @types/bun typescript

With @types/bun installed, Bun.serve, Bun.file, import.meta.dir and bun:test imports all get autocomplete.

Type-only imports

Since types vanish at run time, importing a type with an ordinary import can confuse a transpiler that works file by file: it cannot know whether User is a type (to remove) or a value (to keep). Mark types explicitly:

TypeScript
import type { User } from "./models.ts";
import { createUser, type UserRole } from "./models.ts";

Bun is forgiving and drops unused imports, but verbatimModuleSyntax turns forgetting type into an editor error, which is safer when files are later bundled or run elsewhere.

Features that need rewriting

Most syntax is simply erased. A few TypeScript features generate code, and Bun handles them:

Feature Bun behaviour
enum Compiled to an object, as in tsc.
const enum Treated like a regular enum.
namespace Supported for ordinary namespaces.
Parameter properties (constructor(private x: number)) Expanded to field assignments.
declare and ambient types Removed.
Decorators Supported (standard decorators; legacy ones with experimentalDecorators).

If your codebase uses these, nothing changes. If you are writing new code, many teams prefer as const objects over enums, because they work with every tool that strips types:

TypeScript
const Status = {
  Active: "active",
  Archived: "archived",
} as const;

type Status = (typeof Status)[keyof typeof Status];

Path aliases

tsconfig.json paths work at run time in Bun, which is unusual among runtimes:

JSON
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@lib/*": ["src/lib/*"]
    }
  }
}
TypeScript
import { formatPrice } from "@/utils/format";

The same alias works when you bundle with bun build, so you do not need a separate plugin. The module lesson shows more resolution rules.

JSX and TSX

Bun transpiles JSX in .jsx and .tsx files without extra tools. The setting "jsx": "react-jsx" uses the modern automatic runtime: you do not need to import React in every file, and Bun imports react/jsx-runtime for you. Install a library that provides it:

Terminal
bun add react react-dom
TSX
// App.tsx
type ButtonProps = { label: string };

function Button({ label }: ButtonProps) {
  return <button type="button">{label}</button>;
}

console.log(<Button label="Save" />);

Running bun App.tsx prints the element object React creates. To render to HTML on the server:

TSX
import { renderToString } from "react-dom/server";

console.log(renderToString(<Button label="Save" />));

You can use JSX without React. Set jsxImportSource to another library (Preact, Solid, Hono's JSX) in tsconfig.json:

JSON
{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "preact" } }

Bun reads these options at run time and at bundle time. For classic React setups use "jsx": "react" with jsxFactory and jsxFragmentFactory.

JSON, JS and mixed projects

allowJs: true means you can import .js from .ts and vice versa. Importing JSON is typed when resolveJsonModule is on, and Bun parses it natively:

TypeScript
import config from "./config.json";
console.log(config.port);

Common mistakes

  1. Assuming types are enforced. They are not. Check separately.
  2. Forgetting @types/bun. The program runs, but the editor underlines Bun.
  3. Leaving noEmit off. tsc then writes .js files next to your sources.
  4. Mixing "module": "commonjs" with Bun. Use Preserve or ESNext.
  5. Using require in .ts and expecting types. Prefer import; both run, but only import is well typed.

A stand-in for the checking step

The check script is just a command. This stand-in simulates what a type error report looks like, by validating data at run time instead, which is the other way to catch the same bug:

Node.js Stand-in: a runtime check catches what Bun's transpiler ignores (Node 24)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Libraries such as Zod do this validation for you at the edges of your program, where data enters from outside. Static types plus runtime validation together cover both kinds of mistakes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Bun do with TypeScript type annotations?

    Bun's transpiler erases types without checking them. Use tsc --noEmit for checking.
  2. 2. Which package gives your editor the types for the Bun global?

    @types/bun provides the type definitions for Bun's APIs.
  3. 3. What does the jsx react-jsx setting mean?

    react-jsx uses the automatic JSX runtime, importing jsx helpers from react/jsx-runtime for you.
  4. 4. Do tsconfig.json path aliases work when running files with bun?

    Bun honours compilerOptions.paths for both running and bundling.

Summary

  • Bun runs .ts, .tsx and .jsx directly: it erases types and compiles JSX natively.
  • Bun does not type-check. Run tsc --noEmit in a check script and in CI.
  • Use the bun init tsconfig: moduleResolution: bundler, module: Preserve, noEmit, strict.
  • Install @types/bun so editors understand Bun's globals.
  • Path aliases from tsconfig.json work at run time; use import type for types.
  • JSX works out of the box; set jsxImportSource for libraries other than React.

Next: Modules and Imports