Setting Up a TypeScript App with Bun

If you’ve been managing TypeScript projects with Node.js, you know the friction: install ts-node or tsx, configure a build step, wire up your scripts, and only then start writing code. Bun removes most of that overhead. It’s a modern JavaScript runtime that runs TypeScript files directly, ships with a built-in package manager, and acts as a task runner—all in one tool. This guide walks you through a complete Bun TypeScript project setup so you can go from zero to running TypeScript in minutes.

What Is Bun and Why Use It for TypeScript?

Bun is a fast JavaScript runtime built on JavaScriptCore and written in Zig. What makes it stand out for TypeScript development is that it natively transpiles .ts and .tsx files at runtime—no separate build step required. Unlike the Node.js + ts-node combination, Bun handles transpilation internally, which means noticeably faster startup times and a simpler development workflow.

Beyond the runtime, Bun replaces several tools at once:

• Runtime – executes TypeScript and JavaScript directly
• Package manager – faster alternative to npm, yarn, or pnpm
• Task runner – runs scripts defined in package.json

Creating a New Bun TypeScript Project

Start by installing Bun, then scaffold a new project:

bun init

Bun will prompt you for an entry point. Use src/index.ts to keep things organized:

entry point (index.ts): src/index.ts

This generates a minimal project structure:

my-app/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── bun.lock

The bun.lock file is Bun’s dependency lockfile used by Bun’s package manager to ensure consistent installs.

Installing Bun Type Definitions

If @types/bun is not already present in your project, install it as a dev dependency to get proper IntelliSense and type checking for Bun-specific APIs:

bun add -d @types/bun

This gives you typed access to Bun’s built-in APIs like Bun.serve(), Bun.file(), and bun:sqlite. See the official Bun TypeScript documentation for more details.

Recommended tsconfig.json for Bun Projects

Bun works without a tsconfig.json, but you’ll want one for IDE support and type checking. The key setting for Bun TypeScript configuration is "moduleResolution": "bundler", which aligns with how Bun resolves modules internally.

Other important options to include:

• "target": "ESNext" and "lib": ["ESNext"] — use modern JavaScript features
• "strict": true — catch errors early
• "noEmit": true — Bun handles execution, so you don’t need compiled output
• "verbatimModuleSyntax": true — ensures clean type-only imports
• "allowImportingTsExtensions": true — lets you import .ts files with their extensions

Here is a complete example:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext"],
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ Important: Bun’s transpiler strips type annotations for speed—it does not perform full type checking at runtime. Run bunx tsc --noEmit separately during development or in CI to catch type errors.

Running TypeScript Files and Managing Scripts

Running a TypeScript file with Bun is straightforward:

bun run src/index.ts

For development with automatic restarts on file changes, use watch mode:

bun --watch src/index.ts

Add your common workflows to package.json scripts:

{
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run src/index.ts",
    "typecheck": "bunx tsc --noEmit"
  }
}

Bun runs these scripts directly—no extra task runner needed.

What Else Bun Covers

Once your Bun TypeScript project setup is in place, you have access to several built-in capabilities without adding dependencies:

• Test runner — bun test supports a Jest-compatible API out of the box
• Bundler — bun build handles frontend asset bundling
• SQLite — bun:sqlite provides a native, typed database interface

These aren’t required for a basic setup, but they’re available the moment you need them. You can explore the full feature set in the official Bun documentation.

Conclusion

The main shift when using TypeScript with Bun is accepting that the runtime handles transpilation while tsc handles type safety—they’re separate concerns. Once that clicks, the workflow is clean: initialize a project, install @types/bun if needed, configure your tsconfig.json with bundler-style module resolution, and run your TypeScript files directly. No build pipeline to maintain, no extra tools to install.

FAQs

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.