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.
TypeScript on Bun
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Inspect
package.json, bunfig.toml, tsconfig.json
- fuse-ai-pilot:research-expert - Verify Bun 1.3.x behavior via Context7/Exa
- 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
- Linting / formatting → use ts-lint-format
- Framework runtimes that own their build pipeline (Next.js, Astro)
Critical Rules
- Bun runs
.ts/.tsx natively - Its transpiler handles TS + JSX with no config; unlike Node, .tsx, enum, and decorators work at runtime.
- Bun does NOT down-convert syntax - Recent ECMAScript appears as-is in bundled output; the bundler is not a replacement for
tsc typechecking.
bunfig.toml is Bun-only - It complements, never replaces, package.json and tsconfig.json; CLI flags override bunfig values.bun test is Jest-compatible - Import from bun:test; not every Jest feature is implemented.- 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 for a complete setup
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| bunfig + test |
bunfig-test.md |
Coverage thresholds, JUnit, preload, watch |
| Build + compile |
build-compile.md |
Bun.build, single-file executables, cross-compile |
| Workspaces |
workspaces.md |
Monorepo layout, workspace:*, --filter, catalogs |
| Bun vs Node |
references/bun-vs-node.md |
Choosing a runtime; transpiler differences |
Templates
| Template |
When to Use |
| 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
1---2name: ts-runtime-bun3description: 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).4---56<objective>7This skill covers running TypeScript natively on Bun 1.3.x: configuring bunfig.toml (test8coverage thresholds, JUnit reporter, preload), running bun test (Jest-compatible API via9bun:test), bundling with Bun.build or producing a single-file executable with bun build10--compile --target=, and structuring a Bun workspaces monorepo.1112It also covers the Bun-vs-Node tradeoff — Bun runs .ts/.tsx natively with no transpile step13and does not down-convert modern syntax, but neither its runtime nor bundler perform type14checking, so tsc --noEmit stays in CI regardless.1516Out of scope: Node.js runtime setup (native type stripping, node:test) belongs to17ts-runtime-node; tsconfig details belong to ts-config.18</objective>1920# TypeScript on Bun2122## Agent Workflow (MANDATORY)2324Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:25261. **fuse-ai-pilot:explore-codebase** - Inspect `package.json`, `bunfig.toml`, `tsconfig.json`272. **fuse-ai-pilot:research-expert** - Verify Bun 1.3.x behavior via Context7/Exa283. **mcp__context7__query-docs** - Check Bun runtime, test, and bundler docs2930After implementation, run **fuse-ai-pilot:sniper** for validation.3132## Use when3334- Running `.ts`/`.tsx` directly on Bun with no separate transpile step35- Configuring `bunfig.toml` (`[test]` coverage thresholds, JUnit reporter, preload)36- Bundling with `Bun.build` / `bun build`, or producing a `--compile` single-file binary37- Structuring a Bun **workspaces** monorepo38- Deciding **Bun vs Node** for a given project3940## Do NOT use for4142- Node's native type stripping / `node:test` → use [ts-runtime-node](../ts-runtime-node/SKILL.md)43- Linting / formatting → use [ts-lint-format](../ts-lint-format/SKILL.md)44- Framework runtimes that own their build pipeline (Next.js, Astro)4546## Critical Rules47481. **Bun runs `.ts`/`.tsx` natively** - Its transpiler handles TS + JSX with no config; unlike Node, `.tsx`, `enum`, and decorators work at runtime.492. **Bun does NOT down-convert syntax** - Recent ECMAScript appears as-is in bundled output; the bundler is not a replacement for `tsc` typechecking.503. **`bunfig.toml` is Bun-only** - It complements, never replaces, `package.json` and `tsconfig.json`; CLI flags override `bunfig` values.514. **`bun test` is Jest-compatible** - Import from `bun:test`; not every Jest feature is implemented.525. **Type-check separately** - Keep `tsc --noEmit` (or `bun x tsc`) in CI; Bun's runtime and bundler do no type checking.5354## Architecture5556```57monorepo/58├── package.json # "workspaces": ["packages/*"]59├── bunfig.toml # [test] coverage + [test.reporter] junit60├── bun.lock61├── tsconfig.json62└── packages/63 ├── core/ # bun:test, Bun.build64 └── cli/ # bun build --compile → binary65```6667→ See [bun-project-setup.md](references/templates/bun-project-setup.md) for a complete setup6869## Reference Guide7071### Concepts7273| Topic | Reference | When to Consult |74|-------|-----------|-----------------|75| **bunfig + test** | [bunfig-test.md](references/bunfig-test.md) | Coverage thresholds, JUnit, preload, watch |76| **Build + compile** | [build-compile.md](references/build-compile.md) | `Bun.build`, single-file executables, cross-compile |77| **Workspaces** | [workspaces.md](references/workspaces.md) | Monorepo layout, `workspace:*`, `--filter`, catalogs |78| **Bun vs Node** | [references/bun-vs-node.md](references/bun-vs-node.md) | Choosing a runtime; transpiler differences |7980### Templates8182| Template | When to Use |83|----------|-------------|84| [bun-project-setup.md](references/templates/bun-project-setup.md) | Starting a Bun TS project or monorepo |8586## Best Practices8788### DO89- Put coverage thresholds and the JUnit reporter in `bunfig.toml` for CI90- Use `bun test --coverage` and `--reporter=junit --reporter-outfile` in pipelines91- Use `--compile --target=` to cross-compile CLIs for other platforms9293### DON'T94- Treat `bun build` as a typechecker — run `tsc --noEmit` alongside it95- Assume Bun downlevels modern syntax — it does not96- Duplicate `tsconfig` settings into `bunfig.toml` — Bun reads `tsconfig` directly
fusengine