---
name: bun-best-practices
description: Use when working in this repository with Bun scripts, dependency installs, tests, lockfiles, dev servers, Elysia API runtime, or frontend bundling decisions.
---

# Bun Best Practices

This repo is Bun-native: Bun is the package manager, script runner, TypeScript/JSX runtime, test runner, API runtime, and frontend bundler unless a task has a specific compatibility constraint.

## Project Guidance

- Keep dependency declarations in `package.json`, exact resolution state in `bun.lock`, and Bun configuration in `bunfig.toml`. Do not add npm, Yarn, or pnpm lockfiles for normal work.
- Prefer `bun run <script>` for repo scripts: `dev`, `dev:all`, `styles:build`, `web:dev`, `api:dev`, `build`, and `check`.
- Let Bun execute `.ts`, `.tsx`, `.js`, and `.jsx` directly. Avoid `ts-node`, `tsx`, `node --loader`, or transpile-first flows unless an external tool requires them.
- For the Elysia API, treat Bun runtime changes as production-sensitive: add smoke/load checks, watch RSS/native memory as well as JS heap, handle client disconnects for long-lived responses, keep monitoring visible, and preserve a rollback path for runtime upgrades.
- Prefer Bun's built-in test runner for new simple TypeScript-first tests, but preserve Jest/Vitest when existing tests depend on their exact mocking, isolation, or DOM behavior.

## Quick Reference

| Task | Preferred command |
| --- | --- |
| Install/update deps | `bun install` |
| Reproducible CI install | `bun ci` |
| Run all dev surfaces | `bun run dev:all` |
| Run API dev server | `bun run api:dev` |
| Run web dev server | `bun run web:dev` |
| Build | `bun run build` |
| Check project | `bun run check` |
| Run tests | `bun test` |
| Restart on file changes | `bun --watch run <script>` |
| Hot reload preserving global state | `bun --hot run <script>` |

`bun run` resolves package scripts first, then files, package binaries, and finally system commands. If a command name is ambiguous, prefer the explicit package script.

## Common Mistakes

- Putting watch flags after `run`: use `bun --watch run api:dev`, not `bun run --watch api:dev`.
- Confusing `--watch` and `--hot`: `--watch` restarts the process; `--hot` soft reloads and preserves global state.
- Using `bun install` in CI when reproducibility matters: use `bun ci` so the lockfile is frozen.
- Adding Node-centric shims because TypeScript is present: Bun already executes TS/JSX directly.
- Treating runtime adoption as risk-free: Bun is excellent for tooling and dev speed, but production runtime changes still need load/smoke coverage, memory monitoring, disconnect cleanup, and rollback.