DEV Community

Olivia Craft
Olivia Craft

Posted on

CLAUDE.md for Bun: 13 Rules That Stop AI from Treating It Like Node.js

#bunjs #claudemd #typescript #javascript

Bun is not Node.js. It's not a drop-in replacement with a different name. It has its own bundler, test runner, package manager, and native TypeScript support — none of which exist in Node.js without additional tools.

When AI generates code for a Bun project without explicit context, it defaults to Node.js patterns: ts-node for TypeScript execution, jest for testing, webpack or Vite for bundling, npm for packages. These work, but they bypass everything that makes Bun fast.

A CLAUDE.md file that declares "this is a Bun project" removes the confusion. Here are 13 rules that cover the most common drift patterns.

Rule 1: Declare Bun as the runtime 

This project uses Bun as the runtime, package manager, bundler,
and test runner. Do NOT generate Node.js-specific patterns:
- No ts-node or tsx for TypeScript execution
- No jest or vitest (use Bun's built-in test runner)
- No webpack, Vite, or esbuild config (use Bun's bundler)
- No npm or yarn (use bun install / bun add)
Run TypeScript files directly: bun run file.ts
Enter fullscreen mode Exit fullscreen mode

Rule 2: Bun's built-in test runner replaces Jest 

Tests use Bun's native test runner:
  import { test, expect, describe } from "bun:test"
  bun test to run all tests
Do NOT install or configure jest, vitest, or mocha.
Bun's test runner is Jest-compatible for basic assertions.
Enter fullscreen mode Exit fullscreen mode

Rule 3: Bun's bundler replaces webpack/Vite 

For bundling: bun build ./src/index.ts --outdir ./dist
For dev server with hot reload: bun --hot run src/index.ts
Do NOT generate webpack.config.js, vite.config.ts, or
esbuild scripts unless the project explicitly requires them.
Enter fullscreen mode Exit fullscreen mode

Rule 4: Package management uses Bun commands 

Install packages: bun add <package>
Install dev packages: bun add -d <package>
Install all deps: bun install
Run scripts: bun run <script>
Do NOT use npm install, npm run, yarn, or pnpm commands.
Lock file: bun.lockb (binary format — do not edit manually)
Enter fullscreen mode Exit fullscreen mode

Rule 5: TypeScript runs natively — no compilation step 

Bun executes TypeScript directly without tsc or ts-node.
Do NOT add a tsconfig.json build step or compilation script.
For type checking only: bunx tsc --noEmit
For runtime: bun run file.ts (no compile step)
Enter fullscreen mode Exit fullscreen mode

Rule 6: Bun's HTTP server uses Bun.serve() 

HTTP servers use Bun's native HTTP API:
  Bun.serve({
    port: 3000,
    fetch(req) { return new Response("ok") }
  })
Do NOT use Express, Fastify, or http.createServer() unless
the project explicitly requires Node.js HTTP compatibility.
Enter fullscreen mode Exit fullscreen mode

Rule 7: File I/O uses Bun APIs 

Read file: await Bun.file("path").text()
Write file: await Bun.write("path", content)
Do NOT use fs.readFile, fs.promises, or Node.js fs module
when Bun's native file API can handle it.
Enter fullscreen mode Exit fullscreen mode

Rule 8: Environment variables use Bun.env 

Environment variables: Bun.env.VAR_NAME
Bun auto-loads .env files — no dotenv import needed.
Do NOT install or import dotenv.
Enter fullscreen mode Exit fullscreen mode

Rule 9: Bun's shell API for subprocess execution 

For running shell commands: use Bun.$ template literal API
  const result = await Bun.$`ls -la`.text()
Do NOT use child_process.exec or child_process.spawn
when Bun.$ handles the use case.
Enter fullscreen mode Exit fullscreen mode

Rule 10: SQLite uses Bun's built-in driver 

For SQLite: import { Database } from "bun:sqlite"
Do NOT install better-sqlite3 or sqlite3 npm packages
for SQLite access — Bun includes a native SQLite driver.
Enter fullscreen mode Exit fullscreen mode

Rule 11: Watch mode uses Bun flags 

For development with restart on file change:
  bun --watch run src/index.ts
For hot module replacement (HTTP servers):
  bun --hot run src/index.ts
Do NOT use nodemon, chokidar, or tsx --watch.
Enter fullscreen mode Exit fullscreen mode

Rule 12: WebSockets use Bun.serve() with websocket handler 

WebSocket servers use Bun's native WebSocket support:
  Bun.serve({ websocket: { message(ws, msg) { ... } } })
Do NOT install ws, socket.io, or websocket npm packages
unless the project requires client-side or cross-runtime compat.
Enter fullscreen mode Exit fullscreen mode

Rule 13: Decision order for any Bun code 

When generating code for this project, check in order:
1. Is there a Bun built-in? (Bun.file, Bun.serve, Bun.$, bun:test, bun:sqlite) Use it.
2. Is there a Bun-native API that replaces an npm package? Use it.
3. Only then: use an npm package for features Bun doesn't cover.
Do not skip step 1-2 because the npm equivalent is familiar.
Enter fullscreen mode Exit fullscreen mode

The full CLAUDE.md block 

# Bun Project Rules

## Runtime
- Bun — NOT Node.js
- TypeScript runs natively: bun run file.ts (no tsc step)
- No ts-node, tsx, or compilation scripts

## Package Management
- bun add / bun install (NOT npm/yarn/pnpm)
- Lock file: bun.lockb (binary, don't edit)

## Built-in Tools (use instead of npm packages)
- Tests: bun:test (import { test, expect } from "bun:test")
- Bundler: bun build (no webpack/Vite config)
- Dev server: bun --hot run or bun --watch run
- HTTP: Bun.serve()
- File I/O: Bun.file() + Bun.write()
- SQLite: bun:sqlite
- Shell: Bun.$ template literal
- Env vars: Bun.env.VAR (auto-loads .env)

## Do NOT install:
- jest, vitest, mocha
- nodemon, chokidar, tsx watch
- dotenv
- better-sqlite3, sqlite3
- webpack, Vite, esbuild (unless explicitly required)

## Decision Order
1. Bun built-in -> 2. Bun-native API -> 3. npm package
Enter fullscreen mode Exit fullscreen mode

Why Bun AI drift is the default

Node.js has 15+ years of tutorials, Stack Overflow answers, and training data. Bun 1.0 launched in September 2023. Every "how do I run TypeScript in JavaScript" tutorial on the web reaches for ts-node. Every "how do I write tests" article reaches for Jest.

Without explicit instruction, AI generates what it was trained on. The CLAUDE.md file is the explicit instruction that redirects it to the Bun-native path.

These 13 rules are part of a framework-specific CLAUDE.md series. The Cursor Rules Pack equivalent (50 production-tested rules across all stacks) is available at oliviacraftlat.gumroad.com/l/wyaeil — search "Olivia Craft Cursor Rules" on Gumroad.

Top comments (0)