/ CLAUDE.md
CLAUDE.md
1 --- 2 description: Use Bun instead of Node.js, npm, pnpm, or vite. 3 globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json" 4 alwaysApply: false 5 --- 6 7 Default to using Bun instead of Node.js. 8 9 - Use `bun <file>` instead of `node <file>` or `ts-node <file>` 10 - Use `bun test` instead of `jest` or `vitest` 11 - Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild` 12 - Use `bun install` instead of `npm install` or `yarn install` or `pnpm install` 13 - Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>` 14 - Use `bunx <package> <command>` instead of `npx <package> <command>` 15 - Bun automatically loads .env, so don't use dotenv. 16 17 ## APIs 18 19 - `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`. 20 - `bun:sqlite` for SQLite. Don't use `better-sqlite3`. 21 - `Bun.redis` for Redis. Don't use `ioredis`. 22 - `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`. 23 - `WebSocket` is built-in. Don't use `ws`. 24 - Prefer `Bun.file` over `node:fs`'s readFile/writeFile 25 - Bun.$`ls` instead of execa. 26 27 ## Testing 28 29 Use `bun test` to run tests. 30 31 ```ts#index.test.ts 32 import { test, expect } from "bun:test"; 33 34 test("hello world", () => { 35 expect(1).toBe(1); 36 }); 37 ``` 38 39 ## Frontend 40 41 Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind. 42 43 Server: 44 45 ```ts#index.ts 46 import index from "./index.html" 47 48 Bun.serve({ 49 routes: { 50 "/": index, 51 "/api/users/:id": { 52 GET: (req) => { 53 return new Response(JSON.stringify({ id: req.params.id })); 54 }, 55 }, 56 }, 57 // optional websocket support 58 websocket: { 59 open: (ws) => { 60 ws.send("Hello, world!"); 61 }, 62 message: (ws, message) => { 63 ws.send(message); 64 }, 65 close: (ws) => { 66 // handle close 67 } 68 }, 69 development: { 70 hmr: true, 71 console: true, 72 } 73 }) 74 ``` 75 76 HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle. 77 78 ```html#index.html 79 <html> 80 <body> 81 <h1>Hello, world!</h1> 82 <script type="module" src="./frontend.tsx"></script> 83 </body> 84 </html> 85 ``` 86 87 With the following `frontend.tsx`: 88 89 ```tsx#frontend.tsx 90 import React from "react"; 91 import { createRoot } from "react-dom/client"; 92 93 // import .css files directly and it works 94 import './index.css'; 95 96 const root = createRoot(document.body); 97 98 export default function Frontend() { 99 return <h1>Hello, world!</h1>; 100 } 101 102 root.render(<Frontend />); 103 ``` 104 105 Then, run index.ts 106 107 ```sh 108 bun --hot ./index.ts 109 ``` 110 111 For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.