TypeScript + Bun
Category: Tech Stack · Areas: all
Description
Category
tech-stack
Areas
all
Slot
language-runtime
Components
- Language: TypeScript (strict mode)
- Runtime: Bun 1.x — NOT Node.js
- Package manager: Bun (
bun install,bun add) — NOT npm, NOT yarn, NOT pnpm - Linter + Formatter: Biome — NOT ESLint, NOT Prettier
- Test runner:
bun:test— NOT Vitest, NOT Jest - Configuration:
zodschema parsed over merged layers (committed JSON files +process.env, which Bun also exposes as the equivalentBun.env) in oneenv.ts— NOT scatteredprocess.env/Bun.envreads, NOTdotenv(Bun loads.envnatively) - Workspace layout: Bun workspaces (
workspacesin rootpackage.json) - TypeScript config: strict,
noUncheckedIndexedAccess,exactOptionalPropertyTypes
Constraints
- All code must pass
tsc --noEmit(orbun run typecheck) with strict config - All code must pass Biome lint + format check (
bun run lint) - Scripts use
bun run, notnpm run - Use Bun-native APIs:
Bun.serve()for HTTP (not@hono/node-serveror similar Node adapters),Bun.file()for file I/O,Bun.spawn()for subprocesses - Do not use
tsx,ts-node, or other TypeScript transpilers — Bun runs.tsnatively - Do not add an
engines.nodefield — this project targets Bun, not Node.js - No
package-lock.jsonoryarn.lock— usebun.lock - No
node dist/index.jsstart commands — usebun src/index.ts - Biome config: indent style tabs, line width 100,
noUnusedImports: error - All configuration is declared in one central
zodschema (single module, e.g.env.ts) that parses the merged layers (files + env) once at startup and exports a frozen, typed config object; invalid or missing config fails at startup, not at first use process.env(orBun.env) is read only inside the env module — useprocess.envso the module also runs under Next.js on Node or Edge, whereBun.envis undefined; the config object is built at the entrypoint and passed in- Secrets are never logged or serialized (wrap in a redacting type or omit from log output)
- Config layering and
.envrules followtwelve-factor; hereconfig/default.jsonandconfig/<env>.jsonare deep-merged underprocess.envand parsed by the onezodschema (.env.<env>/.env.localare not used; Bun loads them natively, so set--env-fileexplicitly or none)
Drift Signals (anti-patterns to reject in review)
npm runin scripts → must bebun runprettieroreslintdependencies → replace with Biomevitestorjest→ replace withbun:testtsxorts-node→ remove; Bun executes TypeScript natively@hono/node-serveror any*-node-*HTTP adapter → useBun.serve()node dist/start command → usebun src/engines.nodeconstraint → removeprocess.env.X/Bun.env.Xoutside the env module → read from the typed config object
When to use
TypeScript projects using Bun as the runtime and package manager. Applies to monorepos and single-package projects alike. If a project historically drifted to Node.js tooling (npm, tsx, prettier, vitest), the concern documents the target state and the drift signals above identify what needs correction.
Artifact Impact
Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):
- TD: strict tsconfig, Bun-native APIs, workspace layout, Biome config, central env schema and its config-key contract (owner and source per key)
Practices by activity
Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.
Requirements (Frame activity)
- All user stories involving TypeScript must assume Bun as runtime and package manager
- If a library dependency requires a Node.js adapter, flag it as a concern at framing — it may require a Bun-compatible alternative
Design
- Centralize configuration in one
zodschema inenv.ts(e.g.z.object({ LOG_LEVEL: z.enum(["info", "debug"]).default("info"), DATABASE_URL: z.string().url() })); parseprocess.envonce (notBun.env, so the module also runs under Next.js on Node or Edge) withsafeParseand exit with a readable error on failure - Source precedence per
twelve-factor: plain deep-merge ofconfig/default.jsonandconfig/<env>.jsonunder the environment, thensafeParse; use flatUPPER_SNAKEkeys in the JSON files so env vars map one-to-one env.tsreadsprocess.env.APP_ENVonce, before the deep-merge, to pickconfig/<env>.json; that one read is covered by the module’s existingnoProcessEnvsuppression- Use Bun workspaces for monorepos:
"workspaces": ["packages/*"]in rootpackage.json - Separate packages by concern:
shared(types/schemas),server(API),web(frontend) - Use workspace references (
workspace:*) for cross-package dependencies - HTTP servers:
Bun.serve()— not Express, Fastify with Node adapter, or@hono/node-server - For Hono: use
honodirectly withBun.serve()export, not the node-server adapter
Implementation
- Run TypeScript directly:
bun src/index.ts— no build step required for server/CLI - Scripts in
package.jsonmust usebun run/bun test/bun add, notnpm run - Use Bun-native APIs:
- File I/O:
Bun.file(),Bun.write() - Subprocesses:
Bun.spawn(),Bun.spawnSync() - HTTP:
Bun.serve() - Environment:
process.env/Bun.env(read only in the env module)
- File I/O:
- TypeScript config:
strict,noUncheckedIndexedAccess,exactOptionalPropertyTypes,verbatimModuleSyntax - No
any— TypeScript strict mode is enforced - Formatting: Biome with tabs, line width 100
- Linting: Biome recommended rules +
noUnusedImports: error,noUnusedVariables: warn - Imports: use
typekeyword for type-only imports (import type { Foo })
Testing
- Framework:
bun:test(built-in) - Config in tests: parse an explicit object through the env schema; never depend on a developer’s
.env - Run:
bun test - Use
mock()frombun:testfor module mocking - Fake data:
@faker-js/fakeror equivalent — not static fixtures - Prefer stubs to mocks; verify behavior, not call sequences
- Integration tests can use real databases via
docker compose up -dor testcontainers
Quality Gates (pre-commit / CI)
bun test— all tests passbun run typecheck—tsc --noEmitpasses for all packagesbun run lint— Biome lint + format check passes- No
process.env/Bun.envoutside the env module (BiomenoProcessEnvcoversprocess.env; add a grep gate forBun.env, which the rule does not cover; the env module opts out withbiome-ignore) - Biome
noExcessiveCognitiveComplexityand the file-size cap are set percode-shape-ceilings; no ceiling is raised and nobiome-ignoreis added for them - No
package-lock.jsoncommitted (indicates npm was used) bun.lockcommitted and up to date
Dependency Management
- Add:
bun add <pkg>(notnpm install) - Dev deps:
bun add -d <pkg> - Workspace deps: reference with
"workspace:*"in package.json - Lock file:
bun.lock(text format, committed) - Audit:
bun auditfor known vulnerabilities
Composed-Concern Friction (known)
- Bun-native APIs require the Bun runtime at execution, not just at install.
Modules like
bun:sqlite,Bun.serve(), andBun.file()resolve only when the process is the Bun runtime. A tool that shells out to Node — notablynext build/next startfrom thereact-nextjsconcern — fails to resolveimport { Database } from "bun:sqlite"because the Next.js build/runtime is Node, not Bun. - Fix: force the Bun runtime with
bun --bun. Run Next.js (and any tool that would otherwise spawn Node) underbun --bun run <script>sobun:*built-ins resolve. Without--bun,bun run next buildstill hands execution to Node and the import fails. - Alternative: keep
bun:sqliteout of the Next.js build/runtime path — isolate it in a separate Bun-runtime service/process and reach it over an interface the Next.js layer can call. Choose--bunfor a single-process app; choose isolation when the frontend must build/run under plain Node. - When both
typescript-bunandreact-nextjsare active, declare which resolution the project uses as a project override inconcerns.mdso the choice is explicit rather than rediscovered at build time.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
concerns/typescript-bun.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:3c811513…e5c599f0
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/concerns/typescript-bun/",
"digest": {
"alg": "sha256",
"value": "3c81151337de8e09b7b7d991a907ed0becccd99eea72e897aec09217e5c599f0"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "IS57L7NoJ7ge3--RjxHbmrszzV4S6jqriXIOOyt2lk_ecpb1LOqHxqOc3Rfb4dUrxbcZcxqElPWSdHS7NJAiAw",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}