Running TypeScript directly with Bun: a zero-config script workflow

Developers often face friction when running TypeScript outside a full build pipeline: invoking tsc, configuring tsconfig.json, and waiting for compilation before execution adds latency, especially for small scripts or prototype work. Bun addresses this by enabling native TypeScript execution with zero configuration: bun script.ts runs the file directly, leveraging JavaScriptCore (Apple's high-performance JavaScript engine) for fast startup and built-in support for fetch, WebSocket, and ES modules without polyfills.

Requirements for direct TypeScript execution

Bun works as a standalone runtime. You need Bun installed (via bun install or the system package manager) and a TypeScript file. No tsconfig.json, no node_modules setup is required for simple scripts, though projects with path aliases or strict configuration may benefit from a minimal tsconfig.json.

Smallest suitable design: running a script with Bun

The most basic use case is a single-file script. Create hello.ts:

import { print } from "bun";
print("Hello, world.");

Running it requires no prior compilation:

bun hello.ts

Bun’s built-in TypeScript support parses and executes the file on the fly. The print function is Bun-specific; standard console.log also works via Node.js compatibility shims.

Trust and data boundaries

Bun provides built-in fetch, WebSocket, and ES module interop without polyfills, which works well for networking scripts and tools that consume or produce HTTP data. However, Bun’s API surface is not a superset of Node.js. Globals like process, require, and Buffer exist but may have different behavior or shape. If your script relies on a specific Node.js API, verify compatibility before deploying.

Operational checks and verification

To confirm native TypeScript execution, run:

bun --version

Expected output: a version string (e.g., bun 1.2.3).

bun script.ts

Successful execution without a prior tsc step confirms the feature. For a startup-time comparison, time the run:

time bun script.ts

Compare the output against time node compiled.js (after tsc) to observe the latency reduction attributed to JavaScriptCore.

Required permissions: these commands run without elevated privileges. On macOS/Linux, ensure Bun is on your PATH.

Failure modes and conditions that would change the design

Not all TypeScript features are supported identically across Bun releases. Decorators, advanced type syntax, or certain tsconfig compiler options may require configuration or are unsupported. Additionally, Bun’s compatibility layer does not cover every Node.js API; scripts using require of CommonJS packages may need adjustments or a transpilation step.

If your project depends on unsupported TypeScript features or Node APIs unavailable in Bun, revert to the traditional tsc + node pipeline or evaluate a gradual migration where critical modules are transpiled while others run natively.