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).4versions:5 bun: "1.3.x"6 typescript: "5.8+ (latest stable 6.0)"7references: references/bunfig-test.md, references/build-compile.md, references/workspaces.md, references/bun-vs-node.md, references/templates/bun-project-setup.md8related-skills: ts-runtime-node, ts-lint-format, solid-generic9metadata:10 source: https://skillmd.com/skills/fusengine/ts-runtime-bun11---1213<objective>14This skill covers running TypeScript natively on Bun 1.3.x: configuring bunfig.toml (test15coverage thresholds, JUnit reporter, preload), running bun test (Jest-compatible API via16bun:test), bundling with Bun.build or producing a single-file executable with bun build17--compile --target=, and structuring a Bun workspaces monorepo.1819It also covers the Bun-vs-Node tradeoff — Bun runs .ts/.tsx natively with no transpile step20and does not down-convert modern syntax, but neither its runtime nor bundler perform type21checking, so tsc --noEmit stays in CI regardless.2223Out of scope: Node.js runtime setup (native type stripping, node:test) belongs to24ts-runtime-node; tsconfig details belong to ts-config.25</objective>2627# TypeScript on Bun2829## Agent Workflow (MANDATORY)3031Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:32331. **fuse-ai-pilot:explore-codebase** - Inspect `package.json`, `bunfig.toml`, `tsconfig.json`342. **fuse-ai-pilot:research-expert** - Verify Bun 1.3.x behavior via Context7/Exa353. **mcp__context7__query-docs** - Check Bun runtime, test, and bundler docs3637After implementation, run **fuse-ai-pilot:sniper** for validation.3839## Use when4041- Running `.ts`/`.tsx` directly on Bun with no separate transpile step42- Configuring `bunfig.toml` (`[test]` coverage thresholds, JUnit reporter, preload)43- Bundling with `Bun.build` / `bun build`, or producing a `--compile` single-file binary44- Structuring a Bun **workspaces** monorepo45- Deciding **Bun vs Node** for a given project4647## Do NOT use for4849- Node's native type stripping / `node:test` → use [ts-runtime-node](../ts-runtime-node/SKILL.md)50- Linting / formatting → use [ts-lint-format](../ts-lint-format/SKILL.md)51- Framework runtimes that own their build pipeline (Next.js, Astro)5253## Critical Rules54551. **Bun runs `.ts`/`.tsx` natively** - Its transpiler handles TS + JSX with no config; unlike Node, `.tsx`, `enum`, and decorators work at runtime.562. **Bun does NOT down-convert syntax** - Recent ECMAScript appears as-is in bundled output; the bundler is not a replacement for `tsc` typechecking.573. **`bunfig.toml` is Bun-only** - It complements, never replaces, `package.json` and `tsconfig.json`; CLI flags override `bunfig` values.584. **`bun test` is Jest-compatible** - Import from `bun:test`; not every Jest feature is implemented.595. **Type-check separately** - Keep `tsc --noEmit` (or `bun x tsc`) in CI; Bun's runtime and bundler do no type checking.6061## Architecture6263```64monorepo/65├── package.json # "workspaces": ["packages/*"]66├── bunfig.toml # [test] coverage + [test.reporter] junit67├── bun.lock68├── tsconfig.json69└── packages/70 ├── core/ # bun:test, Bun.build71 └── cli/ # bun build --compile → binary72```7374→ See [bun-project-setup.md](references/templates/bun-project-setup.md) for a complete setup7576## Reference Guide7778### Concepts7980| Topic | Reference | When to Consult |81|-------|-----------|-----------------|82| **bunfig + test** | [bunfig-test.md](references/bunfig-test.md) | Coverage thresholds, JUnit, preload, watch |83| **Build + compile** | [build-compile.md](references/build-compile.md) | `Bun.build`, single-file executables, cross-compile |84| **Workspaces** | [workspaces.md](references/workspaces.md) | Monorepo layout, `workspace:*`, `--filter`, catalogs |85| **Bun vs Node** | [references/bun-vs-node.md](references/bun-vs-node.md) | Choosing a runtime; transpiler differences |8687### Templates8889| Template | When to Use |90|----------|-------------|91| [bun-project-setup.md](references/templates/bun-project-setup.md) | Starting a Bun TS project or monorepo |9293## Best Practices9495### DO96- Put coverage thresholds and the JUnit reporter in `bunfig.toml` for CI97- Use `bun test --coverage` and `--reporter=junit --reporter-outfile` in pipelines98- Use `--compile --target=` to cross-compile CLIs for other platforms99100### DON'T101- Treat `bun build` as a typechecker — run `tsc --noEmit` alongside it102- Assume Bun downlevels modern syntax — it does not103- Duplicate `tsconfig` settings into `bunfig.toml` — Bun reads `tsconfig` directly