Executing TypeScript Directly with Bun: Transpilation and Runtime Configuration

Running TypeScript Without a Build Step

The primary advantage of using Bun is the ability to execute .ts and .tsx files directly without a manual compilation step. Unlike Node.js, which requires tsc or ts-node to convert TypeScript to JavaScript before execution, Bun integrates a high-performance transpiler that handles this conversion in memory at runtime.

To run a TypeScript file, execute the following command in your terminal:

bun run index.ts

Required Permissions: Standard user permissions for the directory containing the file.
Expected Result: The code executes immediately. If the file contains console.log("Hello World"), that string will appear in the stdout.

The Mechanism: Transpilation vs. Type Checking

It is critical to understand that Bun performs transpilation only. Transpilation is the process of stripping TypeScript type annotations (like : string or interface User {}) to create valid JavaScript. Bun does not perform type checking.

This means if you write code that violates your own type definitions, Bun will still execute the file as long as the resulting JavaScript is syntactically valid. To maintain type safety, you must run the TypeScript compiler in "no emit" mode as a separate linting or CI step:

# Run this to find type errors without generating JS files
npx tsc --noEmit

Configuring the Transpiler

While Bun works out-of-the-box, you can control the transpilation behavior using a bunfig.toml file in your project root. This is useful for targeting specific ECMAScript versions or enabling experimental features.

Example: Enabling Experimental Decorators

If your project uses decorators (common in frameworks like NestJS or TypeORM), you must explicitly enable them. Create a bunfig.toml file with the following configuration:

[transpiler]
# Enable support for legacy TypeScript decorators
experimentalDecorators = true
# Target a specific JS version for output
target = "es2022"

Handling Module Systems

Bun treats files as ES Modules (ESM) by default. If you encounter errors when using require() or when integrating older CommonJS (CJS) packages, you can change the module resolution in your package.json:

{
  "name": "my-app",
  "type": "commonjs"
}

Alternatively, renaming a file from .ts to .cts forces Bun to treat that specific file as CommonJS.

Comparison: Bun vs. Traditional TS Tooling

Feature	Bun (Direct Run)	tsc + Node.js	ts-node
Startup Speed	Near-instant	Slow (Build step)	Moderate
Type Checking	None	Full	Optional/Slow
Config File	bunfig.toml / tsconfig.json	tsconfig.json	tsconfig.json
Production Use	Direct or Bun Build	Compiled JS	Not recommended

Limitations and Common Pitfalls

• No .d.ts Emission: Bun's runtime transpiler does not generate declaration files. If you are building a library for other developers, you must use tsc to generate .d.ts files so consumers have type definitions.
• Node-Specific APIs: While Bun has high compatibility with Node.js, using require inside a file treated as an ES Module will throw a runtime error. Use import or adjust the "type" field in package.json.
• Watch Mode Gaps: When using bun --watch, the process may not restart if changes occur in files ignored by the default glob patterns. Check your bunfig.toml to ensure all relevant directories are being watched.

Verification Checklist

To verify your environment is configured correctly, perform these three checks:

1. Execution Check: Run bun index.ts. If it executes without a tsc command, the internal transpiler is working.
2. Type Safety Check: Intentionally add a type error (e.g., let x: number = "string";). Run the file. It should still execute, confirming that Bun is ignoring types for speed.
3. Target Check: Run bun build --outfile out.js index.ts and inspect out.js to ensure the syntax matches your target setting in bunfig.toml.