Run TypeScript Directly with Bun: Zero‑Config Transpilation Explained

Why Bun Makes TypeScript Easy

With Bun you can run bun run myFile.ts and the engine will automatically transpile the file to JavaScript on the fly. No tsc step, no tsconfig.json, no build script – just a single command that bundles dependencies and starts the runtime.

How the Built‑in Transpiler Works

Bun’s transpiler is part of the same engine that powers its JSX transformer. It parses the TypeScript AST, strips out type‑only syntax (e.g. type aliases, interface declarations, import type), and emits ES2022 JavaScript that follows the ES‑module format. Because it runs in the same process as the runtime, the transpilation is extremely fast – often under a millisecond for small files.

Key points:

• Only ES‑module syntax is supported; require() or CommonJS modules are not transpiled.
• It does not perform type checking; type errors surface only at runtime.
• It ignores most tsconfig.json compilerOptions. Defaults are target: ES2022 and module: ES2022.
• It does not emit .d.ts files.
• Built‑in bundling is performed automatically; the output is a single file per entry point.

A Working Example

Create a directory structure:

mkdir -p src
cat > src/app.ts <<'TS'
import { serve } from 'bun';

serve({
  port: 3000,
  fetch(req) {
    return new Response('Hello Bun');
  }
});
TS

Run it with:

bun run src/app.ts

Expected output in the console:

✔  listening on http://localhost:3000

Open http://localhost:3000 and you’ll see Hello Bun – the TypeScript file was transpiled, bundled, and executed in a single step.

Inspecting the Transpiled Code

To see the JavaScript that Bun generated, run:

bun build --compile src/app.ts --outfile out.js
cat out.js | head -n 20

The output will contain plain JavaScript, with all type‑only constructs removed and ES2022 module syntax preserved. Notice that the original import { serve } is kept as an ES module import.

Limitations & Common Pitfalls

Missing Type Checking

Because the transpiler does not run the TypeScript type checker, errors like:

const num: number = 'string';

will not be caught until the code executes, potentially leading to runtime crashes. For a safety net, run tsc --noEmit or use bun test --watch during development.

No .d.ts Generation

If you rely on declaration files for TypeScript consumers, Bun will not produce them. You must generate them separately with tsc --declaration or a dedicated build step.

Ignored tsconfig.json

Options such as target, moduleResolution, or strict are ignored. If you need a different target, use bun build --target esnext or run a conventional tsc build.

Node API Compatibility

Bun’s runtime does not polyfill all Node.js built‑ins. For example, fs.promises is available but may behave differently. Prefer the Bun.fs API when writing Bun‑specific code, and be cautious when porting existing Node modules.

Cache and Watch Mode

Each bun run re‑transpiles files from scratch; large dependency trees can cause noticeable startup latency. Using bun run --watch src/app.ts keeps the transpiled module in memory between changes, improving hot‑reload performance.

Practical Checks & Tips

• Verify Bun version: bun --version should show v1.0 or newer.
• Check transpilation: Use bun build --compile to output a file and inspect it.
• Run type checks separately: Add a pre‑commit hook or CI job that runs tsc --noEmit to catch errors early.
• Use import type for type‑only imports: They are stripped during transpilation and do not add runtime overhead.
• Bundle only what you need: The built‑in bundler includes all dependencies; if you want a smaller bundle, consider using bun build --minify.

By understanding these boundaries, you can leverage Bun’s zero‑config TypeScript support for rapid prototyping while still maintaining type safety and compatibility in larger projects.