remotion_service/.agents/skills/bun-best-practices/SKILL.md

name, description

name	description
bun-best-practices	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.