ts-runtime-bun

---
name: ts-runtime-bun
description: Use when running TypeScript on Bun — bunfig.toml, bun test, Bun.build/--compile, or Bun workspaces. Not for Node.js runtime setup (ts-runtime-node).
versions:
  bun: "1.4.x"
  typescript: "5.8+ (latest stable 7.0)"
references: references/bunfig-test.md, references/build-compile.md, references/workspaces.md, references/bun-vs-node.md, references/templates/bun-project-setup.md
related-skills: ts-runtime-node, ts-lint-format, solid-generic
---

<objective>
This skill covers running TypeScript natively on Bun 1.4.x: configuring bunfig.toml (test
coverage thresholds, JUnit reporter, preload), running bun test (Jest-compatible API via
bun:test), bundling with Bun.build or producing a single-file executable with bun build
--compile --target=, and structuring a Bun workspaces monorepo.

It also covers the Bun-vs-Node tradeoff — Bun runs .ts/.tsx natively with no transpile step
and does not down-convert modern syntax, but neither its runtime nor bundler perform type
checking, so tsc --noEmit stays in CI regardless.

Out of scope: Node.js runtime setup (native type stripping, node:test) belongs to
ts-runtime-node; tsconfig details belong to ts-config.
</objective>

# TypeScript on Bun

## Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Inspect `package.json`, `bunfig.toml`, `tsconfig.json`
2. **fuse-ai-pilot:research-expert** - Verify Bun 1.4.x behavior via Context7/Exa
3. **mcp__context7__query-docs** - Check Bun runtime, test, and bundler docs

After implementation, run **fuse-ai-pilot:sniper** for validation.

## Use when

- Running `.ts`/`.tsx` directly on Bun with no separate transpile step
- Configuring `bunfig.toml` (`[test]` coverage thresholds, JUnit reporter, preload)
- Bundling with `Bun.build` / `bun build`, or producing a `--compile` single-file binary
- Structuring a Bun **workspaces** monorepo
- Deciding **Bun vs Node** for a given project

## Do NOT use for

- Node's native type stripping / `node:test` → use [ts-runtime-node](../ts-runtime-node/SKILL.md)
- Linting / formatting → use [ts-lint-format](../ts-lint-format/SKILL.md)
- Framework runtimes that own their build pipeline (Next.js, Astro)

## Critical Rules

1. **Bun runs `.ts`/`.tsx` natively** - Its transpiler handles TS + JSX with no config; unlike Node, `.tsx`, `enum`, and decorators work at runtime.
2. **Bun does NOT down-convert syntax** - Recent ECMAScript appears as-is in bundled output; the bundler is not a replacement for `tsc` typechecking.
3. **`bunfig.toml` is Bun-only** - It complements, never replaces, `package.json` and `tsconfig.json`; CLI flags override `bunfig` values.
4. **`bun test` is Jest-compatible** - Import from `bun:test`; not every Jest feature is implemented.
5. **Type-check separately** - Keep `tsc --noEmit` (or `bun x tsc`) in CI; Bun's runtime and bundler do no type checking.

## Architecture

```
monorepo/
├── package.json          # "workspaces": ["packages/*"]
├── bunfig.toml           # [test] coverage + [test.reporter] junit
├── bun.lock
├── tsconfig.json
└── packages/
    ├── core/             # bun:test, Bun.build
    └── cli/              # bun build --compile → binary
```

→ See [bun-project-setup.md](references/templates/bun-project-setup.md) for a complete setup

## Reference Guide

### Concepts

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **bunfig + test** | [bunfig-test.md](references/bunfig-test.md) | Coverage thresholds, JUnit, preload, watch |
| **Build + compile** | [build-compile.md](references/build-compile.md) | `Bun.build`, single-file executables, cross-compile |
| **Workspaces** | [workspaces.md](references/workspaces.md) | Monorepo layout, `workspace:*`, `--filter`, catalogs |
| **Bun vs Node** | [references/bun-vs-node.md](references/bun-vs-node.md) | Choosing a runtime; transpiler differences |

### Templates

| Template | When to Use |
|----------|-------------|
| [bun-project-setup.md](references/templates/bun-project-setup.md) | Starting a Bun TS project or monorepo |

## Best Practices

### DO
- Put coverage thresholds and the JUnit reporter in `bunfig.toml` for CI
- Use `bun test --coverage` and `--reporter=junit --reporter-outfile` in pipelines
- Use `--compile --target=` to cross-compile CLIs for other platforms

### DON'T
- Treat `bun build` as a typechecker — run `tsc --noEmit` alongside it
- Assume Bun downlevels modern syntax — it does not
- Duplicate `tsconfig` settings into `bunfig.toml` — Bun reads `tsconfig` directly

• .gitkeep 1 KB
• SKILL.md 5 KB
• references/build-compile.md 3 KB
• references/bun-vs-node.md 2 KB
• references/bunfig-test.md 4 KB
• references/workspaces.md 3 KB
• references/templates/bun-project-setup.md 3 KB