Bun

Specification

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

<prerequisite> You MUST load `javascript` first for language, module, async, and code-navigation conventions. You MUST load `typescript` too when editing TypeScript, type definitions, or tsconfig. </prerequisite>

Use Bun deliberately. Prefer Bun-native APIs in Bun-first projects, but do not break portability by accident.

Bun is an all-in-one JavaScript and TypeScript toolkit: runtime, package manager, test runner, bundler, and script runner. In projects that intentionally target Bun, you SHOULD prefer Bun-native APIs such as

Bun.serve

Bun.file

Bun.write

Bun.$

Bun.spawn

bun:sqlite

, and

bun:test

. In existing Node-compatible projects, you MUST respect the established portability contract and only introduce Bun-specific APIs when the project is already Bun-targeted or the user asks for Bun-specific implementation.

References

Topic	Reference	Load when
HTTP server and routing	`references/server.md`	Building `Bun.serve` apps, routes, cookies, WebSockets, static/file responses
File I/O, shell, and processes	`references/io-and-processes.md`	Using `Bun.file` , `Bun.write` , `Bun.$` , `Bun.spawn` , workers
Testing	`references/testing.md`	Writing `bun:test` tests, mocks, snapshots, coverage, type checks
SQLite, bundler, macros, utilities	`references/ecosystem.md`	Using `bun:sqlite` , `Bun.build` , plugins, macros, passwords, hashing
Configuration and compatibility	`references/config-and-compat.md`	`bunfig.toml` , package manager behavior, Node compatibility, install strategy

Runtime Preferences

Bun-first projects SHOULD use
```
Bun.serve()
```
for HTTP servers,
```
Bun.file()
```
/
```
Bun.write()
```
for file reads and writes,
```
Bun.$
```
for shell commands,
```
Bun.spawn()
```
for child processes,
```
bun:test
```
for tests, and
```
bun:sqlite
```
for SQLite.
Node-compatible projects MAY keep
```
node:*
```
APIs when portability matters, the local codebase already standardizes on them, or Bun has no native equivalent.
Directory traversal and directory creation SHOULD use
```
node:fs/promises
```
unless a Bun-native API has been adopted in the project.
Web-standard APIs such as
```
fetch
```
,
```
Request
```
,
```
Response
```
,
```
ReadableStream
```
,
```
Blob
```
, and
```
AbortController
```
SHOULD be preferred over Node-only abstractions when they fit.
Existing codebase conventions MUST win over this skill. If a convention conflicts, follow the project locally and flag the divergence once.

Server

New Bun HTTP servers SHOULD use
```
Bun.serve({ routes })
```
for declarative routing.
```
fetch
```
SHOULD be used as fallback handling for unmatched routes or for lower-level control such as WebSocket upgrades.
Route handlers SHOULD return
```
Response
```
or
```
Promise<Response>
```
.
```
Bun.serve()
```
SHOULD include an
```
error
```
handler for production-facing servers.
Static
```
Response
```
routes SHOULD be used for health checks, redirects, and fixed JSON responses.
File responses SHOULD choose deliberately between buffering into a static response and returning
```
new Response(Bun.file(path))
```
.

Package Manager

You MUST use the package manager configured by the project. If the project uses Bun or has no established package manager, you SHOULD use Bun commands.
New installs SHOULD use the text
```
bun.lock
```
lockfile. Old
```
bun.lockb
```
projects SHOULD be migrated only when the user asks or the task already requires lockfile work.
CI and reproducible installs SHOULD use
```
bun install --frozen-lockfile
```
.
Dependency lifecycle scripts MUST NOT be trusted casually. Use
```
trustedDependencies
```
or
```
bun pm trust <pkg>
```
only after confirming the package actually requires its install script.
New monorepos SHOULD use isolated installs unless the project requires hoisting. New single-package projects SHOULD use hoisted installs. Existing projects SHOULD preserve their current linker strategy.
Security-sensitive dependency updates SHOULD consider
```
--minimum-release-age
```
to avoid newly published malicious package versions.

Testing And Tooling

Bun-targeted tests SHOULD use
```
bun:test
```
, not Jest or Vitest, unless the project already standardizes elsewhere.
Test files SHOULD import test APIs from
```
bun:test
```
.
Mocks SHOULD be restored or cleared in
```
afterEach
```
when state can leak across tests.
Type assertions from
```
expectTypeOf
```
MUST be paired with a real type-check command such as
```
bunx tsc --noEmit
```
when type correctness is the thing being verified.
Do not run long-lived dev servers or build commands unless the user explicitly asks or approves.

Bundler And Macros

```
Bun.build()
```
SHOULD check
```
result.success
```
and inspect
```
result.logs
```
on failure.
Build targets MUST match the runtime:
```
"bun"
```
for Bun apps,
```
"browser"
```
for browser bundles,
```
"node"
```
for Node output.
Macros are advanced bundler behavior. They SHOULD be used sparingly for small bundle-time computations that replace otherwise separate build scripts.
Macro imports MUST use import attributes such as
```
with { type: "macro" }
```
; do not introduce the older assertion syntax in new code.
Macro return values MUST be serializable by Bun's transpiler, and macro inputs MUST be statically knowable at bundle time.
Macros MUST NOT be treated as runtime imports; they execute at bundle time and carry supply-chain/security risk.

Application

When writing Bun code:

You MUST apply these conventions without narrating each one.
You MUST preserve project portability unless the project is intentionally Bun-targeted.
You SHOULD use Bun-native APIs for new Bun-targeted code.
You MUST keep behavior equivalent when migrating from Node-compatible APIs to Bun-native APIs.

When reviewing Bun code:

You MUST lead with concrete portability, runtime, install, security, or testing risks.
You SHOULD show the smallest Bun-native correction inline.
You MUST distinguish Bun-specific preferences from issues that would affect any JavaScript runtime.

bun

NPX Install

Tags

SKILL.md Content

Bun