mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
Update some docs
This commit is contained in:
Jarred Sumner
238
CLAUDE.md
Normal file
238
CLAUDE.md
Normal file
@@ -0,0 +1,238 @@
|
||||
This is the Bun repository - an all-in-one JavaScript runtime & toolkit designed for speed, with a bundler, test runner, and Node.js-compatible package manager. It's written primarily in Zig with C++ for JavaScriptCore integration, powered by WebKit's JavaScriptCore engine.
|
||||
|
||||
## Building and Running Bun
|
||||
|
||||
### Build Commands
|
||||
|
||||
- **Build debug version**: `bun bd` or `bun run build:debug`
|
||||
- Creates a debug build at `./build/debug/bun-debug`
|
||||
- Compilation takes ~2.5 minutes
|
||||
- **Run tests with your debug build**: `bun bd test <test-file>`
|
||||
- **CRITICAL**: Never use `bun test` directly - it won't include your changes
|
||||
- **Run any command with debug build**: `bun bd <command>`
|
||||
|
||||
### Other Build Variants
|
||||
|
||||
- `bun run build:release` - Release build
|
||||
|
||||
Address sanitizer is enabled by default in debug builds of Bun.
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
- **Single test file**: `bun bd test test/js/bun/http/serve.test.ts`
|
||||
- **Fuzzy match test file**: `bun bd test http/serve.test.ts`
|
||||
- **With filter**: `bun bd test test/js/bun/http/serve.test.ts -t "should handle"`
|
||||
|
||||
### Test Organization
|
||||
|
||||
- `test/js/bun/` - Bun-specific API tests (http, crypto, ffi, shell, etc.)
|
||||
- `test/js/node/` - Node.js compatibility tests
|
||||
- `test/js/web/` - Web API tests (fetch, WebSocket, streams, etc.)
|
||||
- `test/cli/` - CLI command tests (install, run, test, etc.)
|
||||
- `test/regression/issue/` - Regression tests (create one per bug fix)
|
||||
- `test/bundler/` - Bundler and transpiler tests
|
||||
- `test/integration/` - End-to-end integration tests
|
||||
- `test/napi/` - N-API compatibility tests
|
||||
- `test/v8/` - V8 C++ API compatibility tests
|
||||
|
||||
### Writing Tests
|
||||
|
||||
Tests use Bun's Jest-compatible test runner with proper test fixtures:
|
||||
|
||||
```typescript
|
||||
import { test, expect } from "bun:test";
|
||||
import { bunEnv, bunExe, tempDirWithFiles } from "harness";
|
||||
|
||||
test("my feature", async () => {
|
||||
// Create temp directory with test files
|
||||
const dir = tempDirWithFiles("test-prefix", {
|
||||
"index.js": `console.log("hello");`,
|
||||
});
|
||||
|
||||
// Spawn Bun process
|
||||
await using proc = Bun.spawn({
|
||||
cmd: [bunExe(), "index.js"],
|
||||
env: bunEnv,
|
||||
cwd: dir,
|
||||
});
|
||||
|
||||
const [stdout, stderr, exitCode] = await Promise.all([
|
||||
new Response(proc.stdout).text(),
|
||||
new Response(proc.stderr).text(),
|
||||
proc.exited,
|
||||
]);
|
||||
|
||||
expect(exitCode).toBe(0);
|
||||
expect(stdout).toBe("hello\n");
|
||||
});
|
||||
```
|
||||
|
||||
## Code Architecture
|
||||
|
||||
### Language Structure
|
||||
|
||||
- **Zig code** (`src/*.zig`): Core runtime, JavaScript bindings, package manager
|
||||
- **C++ code** (`src/bun.js/bindings/*.cpp`): JavaScriptCore bindings, Web APIs
|
||||
- **TypeScript** (`src/js/`): Built-in JavaScript modules with special syntax (see JavaScript Modules section)
|
||||
- **Generated code**: Many files are auto-generated from `.classes.ts` and other sources
|
||||
|
||||
### Core Source Organization
|
||||
|
||||
#### Runtime Core (`src/`)
|
||||
|
||||
- `bun.zig` - Main entry point
|
||||
- `cli.zig` - CLI command orchestration
|
||||
- `js_parser.zig`, `js_lexer.zig`, `js_printer.zig` - JavaScript parsing/printing
|
||||
- `transpiler.zig` - Wrapper around js_parser with sourcemap support
|
||||
- `resolver/` - Module resolution system
|
||||
- `allocators/` - Custom memory allocators for performance
|
||||
|
||||
#### JavaScript Runtime (`src/bun.js/`)
|
||||
|
||||
- `bindings/` - C++ JavaScriptCore bindings
|
||||
- Generated classes from `.classes.ts` files
|
||||
- Manual bindings for complex APIs
|
||||
- `api/` - Bun-specific APIs
|
||||
- `server.zig` - HTTP server implementation
|
||||
- `FFI.zig` - Foreign Function Interface
|
||||
- `crypto.zig` - Cryptographic operations
|
||||
- `sqlite.zig` - Native SQLite integration
|
||||
- `glob.zig` - File pattern matching
|
||||
- `node/` - Node.js compatibility layer
|
||||
- Module implementations (fs, path, crypto, etc.)
|
||||
- Process and Buffer APIs
|
||||
- `webcore/` - Web API implementations
|
||||
- `fetch.zig` - Fetch API
|
||||
- `streams.zig` - Web Streams
|
||||
- `Blob.zig`, `Response.zig`, `Request.zig`
|
||||
- `event_loop/` - Event loop and task management
|
||||
|
||||
#### Build Tools & Package Manager
|
||||
|
||||
- `src/bundler/` - JavaScript bundler
|
||||
- Advanced tree-shaking
|
||||
- CSS processing
|
||||
- HTML handling
|
||||
- `src/install/` - Package manager
|
||||
- `lockfile/` - Lockfile handling
|
||||
- `npm.zig` - npm registry client
|
||||
- `lifecycle_script_runner.zig` - Package scripts
|
||||
|
||||
#### Other Key Components
|
||||
|
||||
- `src/shell/` - Cross-platform shell implementation
|
||||
- `src/css/` - CSS parser and processor
|
||||
- `src/http/` - HTTP client implementation
|
||||
- `websocket_client/` - WebSocket client (including deflate support)
|
||||
- `src/sql/` - SQL database integrations
|
||||
- `src/bake/` - Server-side rendering framework
|
||||
|
||||
### JavaScript Class Implementation (C++)
|
||||
|
||||
When implementing JavaScript classes in C++:
|
||||
|
||||
1. Create three classes if there's a public constructor:
|
||||
|
||||
- `class Foo : public JSC::JSDestructibleObject` (if has C++ fields)
|
||||
- `class FooPrototype : public JSC::JSNonFinalObject`
|
||||
- `class FooConstructor : public JSC::InternalFunction`
|
||||
|
||||
2. Define properties using HashTableValue arrays
|
||||
3. Add iso subspaces for classes with C++ fields
|
||||
4. Cache structures in ZigGlobalObject
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Code Formatting
|
||||
|
||||
- `bun run prettier` - Format JS/TS files
|
||||
- `bun run zig-format` - Format Zig files
|
||||
- `bun run clang-format` - Format C++ files
|
||||
|
||||
### Watching for Changes
|
||||
|
||||
- `bun run watch` - Incremental Zig compilation with error checking
|
||||
- `bun run watch-windows` - Windows-specific watch mode
|
||||
|
||||
### Code Generation
|
||||
|
||||
Code generation happens automatically as part of the build process. The main scripts are:
|
||||
|
||||
- `src/codegen/generate-classes.ts` - Generates Zig & C++ bindings from `*.classes.ts` files
|
||||
- `src/codegen/generate-jssink.ts` - Generates stream-related classes
|
||||
- `src/codegen/bundle-modules.ts` - Bundles built-in modules like `node:fs`
|
||||
- `src/codegen/bundle-functions.ts` - Bundles global functions like `ReadableStream`
|
||||
|
||||
In development, bundled modules can be reloaded without rebuilding Zig by running `bun run build`.
|
||||
|
||||
## JavaScript Modules (`src/js/`)
|
||||
|
||||
Built-in JavaScript modules use special syntax and are organized as:
|
||||
|
||||
- `node/` - Node.js compatibility modules (`node:fs`, `node:path`, etc.)
|
||||
- `bun/` - Bun-specific modules (`bun:ffi`, `bun:sqlite`, etc.)
|
||||
- `thirdparty/` - NPM modules we replace (like `ws`)
|
||||
- `internal/` - Internal modules not exposed to users
|
||||
- `builtins/` - Core JavaScript builtins (streams, console, etc.)
|
||||
|
||||
### Special Syntax in Built-in Modules
|
||||
|
||||
1. **`$` prefix** - Access to private properties and JSC intrinsics:
|
||||
|
||||
```js
|
||||
const arr = $Array.from(...); // Private global
|
||||
map.$set(...); // Private method
|
||||
const arr2 = $newArrayWithSize(5); // JSC intrinsic
|
||||
```
|
||||
|
||||
2. **`require()`** - Must use string literals, resolved at compile time:
|
||||
|
||||
```js
|
||||
const fs = require("fs"); // Directly loads by numeric ID
|
||||
```
|
||||
|
||||
3. **Debug helpers**:
|
||||
|
||||
- `$debug()` - Like console.log but stripped in release builds
|
||||
- `$assert()` - Assertions stripped in release builds
|
||||
- `if($debug) {}` - Check if debug env var is set
|
||||
|
||||
4. **Platform detection**: `process.platform` and `process.arch` are inlined and dead-code eliminated
|
||||
|
||||
5. **Export syntax**: Use `export default` which gets converted to a return statement:
|
||||
```js
|
||||
export default {
|
||||
readFile,
|
||||
writeFile,
|
||||
};
|
||||
```
|
||||
|
||||
Note: These are NOT ES modules. The preprocessor converts `$` to `@` (JSC's actual syntax) and handles the special functions.
|
||||
|
||||
## Important Development Notes
|
||||
|
||||
1. **Never use `bun test` or `bun <file>` directly** - always use `bun bd test` or `bun bd <command>`. `bun bd` compiles & runs the debug build.
|
||||
2. **Use `await using`** for proper resource cleanup with Bun APIs (Bun.spawn, Bun.serve, Bun.connect, etc.)
|
||||
3. **Follow existing code style** - check neighboring files for patterns
|
||||
4. **Create regression tests** in `test/regression/issue/` when fixing bugs
|
||||
5. **Use absolute paths** - Always use absolute paths in file operations
|
||||
6. **Avoid shell commands** - Don't use `find` or `grep` in tests; use Bun's Glob and built-in tools
|
||||
7. **Memory management** - In Zig code, be careful with allocators and use defer for cleanup
|
||||
8. **Cross-platform** - Test on macOS, Linux, and Windows when making platform-specific changes
|
||||
9. **Debug builds** - Use `BUN_DEBUG_QUIET_LOGS=1` to disable debug logging, or `BUN_DEBUG_<scope>=1` to enable specific scopes
|
||||
10. **Transpiled source** - Find transpiled files in `/tmp/bun-debug-src/` for debugging
|
||||
|
||||
## Key APIs and Features
|
||||
|
||||
### Bun-Specific APIs
|
||||
|
||||
- **Bun.serve()** - High-performance HTTP server
|
||||
- **Bun.spawn()** - Process spawning with better performance than Node.js
|
||||
- **Bun.file()** - Fast file I/O operations
|
||||
- **Bun.write()** - Unified API for writing to files, stdout, etc.
|
||||
- **Bun.$ (Shell)** - Cross-platform shell scripting
|
||||
- **Bun.SQLite** - Native SQLite integration
|
||||
- **Bun.FFI** - Call native libraries from JavaScript
|
||||
- **Bun.Glob** - Fast file pattern matching
|
||||
@@ -144,6 +144,14 @@ $ bun bd test foo.test.ts
|
||||
$ bun bd ./foo.ts
|
||||
```
|
||||
|
||||
Bun generally takes about 2.5 minutes to compile a debug build when there are Zig changes. If your development workflow is "change one line, save, rebuild", you will spend too much time waiting for the build to finish. Instead:
|
||||
|
||||
- Batch up your changes
|
||||
- Ensure zls is running with incremental watching for LSP errors (if you use VSCode and install Zig and run `bun run build` once to download Zig, this should just work)
|
||||
- Prefer using the debugger ("CodeLLDB" in VSCode) to step through the code.
|
||||
- Use debug logs. `BUN_DEBUG_<scope>=1` will enable debug logging for the corresponding `Output.scoped(.<scope>, false)` logs. You can also set `BUN_DEBUG_QUIET_LOGS=1` to disable all debug logging that isn't explicitly enabled. To dump debug lgos into a file, `BUN_DEBUG=<path-to-file>.log`. Debug logs are aggressively removed in release builds.
|
||||
- src/js/\*\*.ts changes are pretty much instant to rebuild. C++ changes are a bit slower, but still much faster than the Zig code (Zig is one compilation unit, C++ is many).
|
||||
|
||||
## Code generation scripts
|
||||
|
||||
Several code generation scripts are used during Bun's build process. These are run automatically when changes are made to certain files.
|
||||
@@ -179,6 +187,7 @@ To run a release build from a pull request, you can use the `bun-pr` npm package
|
||||
bunx bun-pr <pr-number>
|
||||
bunx bun-pr <branch-name>
|
||||
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
|
||||
bunx bun-pr --asan <pr-number> # Linux x64 only
|
||||
```
|
||||
|
||||
This will download the release build from the pull request and add it to `$PATH` as `bun-${pr-number}`. You can then run the build with `bun-${pr-number}`.
|
||||
@@ -189,24 +198,18 @@ bun-1234566 --version
|
||||
|
||||
This works by downloading the release build from the GitHub Actions artifacts on the linked pull request. You may need the `gh` CLI installed to authenticate with GitHub.
|
||||
|
||||
## Valgrind
|
||||
## AddressSanitizer
|
||||
|
||||
On Linux, valgrind can help find memory issues.
|
||||
[AddressSanitizer](https://en.wikipedia.org/wiki/AddressSanitizer) helps find memory issues, and is enabled by default in debug builds of Bun on Linux and macOS. This includes the Zig code and all dependencies. It makes the Zig code take about 2x longer to build, if that's stopping you from being productive you can disable it by setting `-Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false>` to `-Denable_asan=false` in the `cmake/targets/BuildBun.cmake` file, but generally we recommend batching your changes up between builds.
|
||||
|
||||
Keep in mind:
|
||||
|
||||
- JavaScriptCore doesn't support valgrind. It will report spurious errors.
|
||||
- Valgrind is slow
|
||||
- Mimalloc will sometimes cause spurious errors when debug build is enabled
|
||||
|
||||
You'll need a very recent version of Valgrind due to DWARF 5 debug symbols. You may need to manually compile Valgrind instead of using it from your Linux package manager.
|
||||
|
||||
`--fair-sched=try` is necessary if running multithreaded code in Bun (such as the bundler). Otherwise it will hang.
|
||||
To build a release build with Address Sanitizer, run:
|
||||
|
||||
```bash
|
||||
$ valgrind --fair-sched=try --track-origins=yes bun-debug <args>
|
||||
$ bun run build:release:asan
|
||||
```
|
||||
|
||||
In CI, we run our test suite with at least one target that is built with Address Sanitizer.
|
||||
|
||||
## Building WebKit locally + Debug mode of JSC
|
||||
|
||||
WebKit is not cloned by default (to save time and disk space). To clone and build WebKit locally, run:
|
||||
|
||||
Reference in New Issue
Block a user