fusengine/ts-runtime-bun

TypeScript on Bun

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Inspect package.json, bunfig.toml, tsconfig.json
2. fuse-ai-pilot:research-expert - Verify Bun 1.3.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
• Linting / formatting → use ts-lint-format
• 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 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