mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
d7eebef6f8
### What does this PR do?
- **Use `Latin1Character` instead of `LChar`**
- **Fix for
0875bc8f62**
### How did you verify your code works?
---
# WebKit Update Summary (September 2025)
## Overview
This document summarizes the major changes in WebKit/JavaScriptCore from
the September 2025 update. The update includes approximately 254
JSC-related commits with significant improvements to performance,
stability, and developer experience.
## Critical Bug Fixes
### Memory Safety
- **operationMaterializeObjectInOSR fix** (5c7aadfa0a96): Fixed
uninitialized Butterfly storage during OSR exits with sunk Array
allocations. This prevents potential crashes when arrays with holes are
materialized during OSR exit.
- **FTL materialization fixes** (a72d19840714, ed1e6fe03899): Added
missing internal object type handling in FTL materialization, improving
stability during optimization bailouts.
### Promise and Async Improvements
- **JSPromiseReaction object** (a1cb5e087a46, later reverted in
b0566a4db201): Initially introduced to improve promise reaction handling
but was reverted due to compatibility issues with Bun's modifications.
- **Async stack traces enhancements**:
- Added support for `Promise.any` in async stack traces (d9a997b3edaa)
- Added empty JSValue checking for async stack trace safety
(9d26223d4bcb)
- Promise.all support was added and later reverted due to performance
concerns
## Performance Optimizations
### JIT Compiler Improvements
- **B3 Immutable Loads** (570a3530f949, 62300f8db3d9): Added
immutability annotations and CSE optimizations for loads that can look
for targets in dominators
- **BBQ JIT enhancements**:
- Fixed callee-save register handling (c7ae05719045)
- Simplified F32 copysign operations (e0651af57025)
- **DFG optimizations**:
- Fixed RegExp constant folding with materialized NewRegExp nodes
(7b53a04a5afa)
- Improved RegExp object node handling in strength reduction
(eeb65e05095b)
### WebAssembly Improvements
- **WASM SIMD Support**:
- Added v128 support for IPInt call and tail-call instructions
(73f0c9d430cb)
- Implemented v128 support in local.get, local.set, global.get,
global.set (67d7bf15139a)
- Added x86_64 SIMD integer arithmetic and float instructions
- **WASM Memory Management**:
- Introduced WasmInstanceAnchor for better instance lifecycle management
(f9f1ed183bf7)
- Attached AbstractHeap to wasm memory access for better optimization
(f183c6f7def4)
- Added signal handling for null checks in wasm (bf18b5b709f3)
- **WASM Debugging**: Added LLDB debugging infrastructure for
WebAssembly (e03c10225cc8)
## API and Language Features
### Iterator Helpers
- Merged `Iterator.prototype.sliding` into `Iterator.prototype.windows`
(1d49e823702d)
- Optimized iterator next method calls using CachedCall (5ee92514060c)
### Math Extensions
- Improved performance of `Math.sumPrecise` implementation
(602294057337)
### Error Handling
- Enhanced error messages for for-of loops without Symbol.iterator
(0051bbf2491f)
## Infrastructure Changes
### Character Type Refactoring
- **LChar to Latin1Character rename** (63b97b511366, 1424f0687876):
Major refactoring replacing the `LChar` type with `Latin1Character`
throughout the codebase for better clarity
- Additional fixes for Latin1Character usage (711eab3243f0,
50bf8e6fd4ca, 88e29ab76aec)
### Build System
- Fixed builds with GCC 15.x (e33b18bc59d6)
- Added gitattributes for JSC test files (82c4cc796da6)
- Improved test runner with comprehensive verbose logging (7ef95c177a42)
- Added memory-limited annotations for tests using excessive memory
(b991cd17d612)
### Testing Infrastructure
- Improved handling of missing test executables (db1e3bbb3be2)
- Added support for non-customized ICU 74.2 in intl tests (c922a28b6642)
- Fixed various test configuration issues and timeouts
## Bun-Specific Modifications
### Preserved Customizations
- Maintained `BUN_JSC_ADDITIONS` for Bun-specific features
- Kept async context support for AsyncLocalStorage
- Preserved V8 heap snapshot compatibility layer
- Maintained custom inspector extensions
### Conflicts Resolved
- Successfully merged upstream changes while preserving Bun's event loop
integration
- Resolved conflicts in promise handling while maintaining Bun's async
behavior
- Fixed re-declaration issues with `isAsyncFrame` for async stack traces
## Breaking Changes and Reverts
### Reverted Features
1. **JSPromiseReaction object**: Reverted due to conflicts with Bun's
promise handling
2. **Promise.all async stack trace support**: Reverted due to ~4%
performance regression in JetStream3/doxbee-async benchmark
3. **Array.prototype.flat C++ implementation**: Reverted (reason not
specified in commit)
## Security Improvements
- Type safety improvements with uncheckedDowncast for Wasm::Callee
(48425afd643d)
- Added bounds checking and validation for Wasm array operations
(b5148db1c4c1)
- Improved memory safety with proper initialization of materialized
objects
## Platform Support
- macOS: Continued support for x64/arm64
- Linux: Maintained glibc/musl compatibility
- Windows: Preserved x64 support
- Fixed platform-specific alignment issues for x86_64 (94a60eb123c5)
## Notable Debugging Enhancements
- LLDB infrastructure for WebAssembly debugging
- Improved verbose command logging in test runners
- Enhanced stack trace capabilities for async functions
- Better error reporting for missing Symbol.iterator
## Performance Metrics
- Several memory optimizations for test execution
- JIT memory reservation size adjustments for debug builds
- Optimized iterator operations with cached calls
- Improved Math.sumPrecise performance
## Future Considerations
- The JSPromiseReaction implementation may need revisiting with adjusted
architecture
- Async stack trace support for Promise.all requires performance
optimization
- Continued work on WASM SIMD support for additional operations
## Migration Notes for Bun Team
1. **LChar usage**: All references to `LChar` have been replaced with
`Latin1Character`
2. **Promise handling**: The reverted JSPromiseReaction changes indicate
potential architectural conflicts that may need addressing
3. **Test configuration**: New memory-limited annotations should be used
for memory-intensive tests
4. **Build flags**: Ensure USE_BUN_JSC_ADDITIONS and USE_BUN_EVENT_LOOP
remain enabled
Bun
Read the docs →
What is Bun?
Bun is an all-in-one toolkit for JavaScript and TypeScript apps. It ships as a single executable called bun.
At its core is the Bun runtime, a fast JavaScript runtime designed as a drop-in replacement for Node.js. It's written in Zig and powered by JavaScriptCore under the hood, dramatically reducing startup times and memory usage.
bun run index.tsx # TS and JSX supported out-of-the-box
The bun command-line tool also implements a test runner, script runner, and Node.js-compatible package manager. Instead of 1,000 node_modules for development, you only need bun. Bun's built-in tools are significantly faster than existing options and usable in existing Node.js projects with little to no changes.
bun test # run tests
bun run start # run the `start` script in `package.json`
bun install <pkg> # install a package
bunx cowsay 'Hello, world!' # execute a package
Install
Bun supports Linux (x64 & arm64), macOS (x64 & Apple Silicon) and Windows (x64).
Linux users — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.
x64 users — if you see "illegal instruction" or similar errors, check our CPU requirements
# with install script (recommended)
curl -fsSL https://bun.com/install | bash
# on windows
powershell -c "irm bun.com/install.ps1 | iex"
# with npm
npm install -g bun
# with Homebrew
brew tap oven-sh/bun
brew install bun
# with Docker
docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun
Upgrade
To upgrade to the latest version of Bun, run:
bun upgrade
Bun automatically releases a canary build on every commit to main. To upgrade to the latest canary build, run:
bun upgrade --canary
Quick links
-
Intro
-
Templating
-
CLI
-
Runtime
-
Package manager
-
Bundler
-
Test runner
-
Package runner
-
API
- HTTP server (
Bun.serve) - WebSockets
- Workers
- Binary data
- Streams
- File I/O (
Bun.file) - import.meta
- SQLite (
bun:sqlite) - PostgreSQL (
Bun.sql) - Redis (
Bun.redis) - S3 Client (
Bun.s3) - FileSystemRouter
- TCP sockets
- UDP sockets
- Globals
- $ Shell
- Child processes (spawn)
- Transpiler (
Bun.Transpiler) - Hashing
- Colors (
Bun.color) - Console
- FFI (
bun:ffi) - C Compiler (
bun:fficc) - HTMLRewriter
- Testing (
bun:test) - Cookies (
Bun.Cookie) - Utils
- Node-API
- Glob (
Bun.Glob) - Semver (
Bun.semver) - DNS
- fetch API extensions
- HTTP server (
Guides
-
Binary
- Convert a Blob to a string
- Convert a Buffer to a blob
- Convert a Blob to a DataView
- Convert a Buffer to a string
- Convert a Blob to a ReadableStream
- Convert a Blob to a Uint8Array
- Convert a DataView to a string
- Convert a Uint8Array to a Blob
- Convert a Blob to an ArrayBuffer
- Convert an ArrayBuffer to a Blob
- Convert a Buffer to a Uint8Array
- Convert a Uint8Array to a Buffer
- Convert a Uint8Array to a string
- Convert a Buffer to an ArrayBuffer
- Convert an ArrayBuffer to a Buffer
- Convert an ArrayBuffer to a string
- Convert a Uint8Array to a DataView
- Convert a Buffer to a ReadableStream
- Convert a Uint8Array to an ArrayBuffer
- Convert an ArrayBuffer to a Uint8Array
- Convert an ArrayBuffer to an array of numbers
- Convert a Uint8Array to a ReadableStream
-
Ecosystem
- Use React and JSX
- Use EdgeDB with Bun
- Use Prisma with Bun
- Add Sentry to a Bun app
- Create a Discord bot
- Run Bun as a daemon with PM2
- Use Drizzle ORM with Bun
- Build an app with Nuxt and Bun
- Build an app with Qwik and Bun
- Build an app with Astro and Bun
- Build an app with Remix and Bun
- Build a frontend using Vite and Bun
- Build an app with Next.js and Bun
- Run Bun as a daemon with systemd
- Deploy a Bun application on Render
- Build an HTTP server using Hono and Bun
- Build an app with SvelteKit and Bun
- Build an app with SolidStart and Bun
- Build an HTTP server using Elysia and Bun
- Build an HTTP server using StricJS and Bun
- Containerize a Bun application with Docker
- Build an HTTP server using Express and Bun
- Use Neon Postgres through Drizzle ORM
- Server-side render (SSR) a React component
- Read and write data to MongoDB using Mongoose and Bun
- Use Neon's Serverless Postgres with Bun
-
HTMLRewriter
-
HTTP
- Hot reload an HTTP server
- Common HTTP server usage
- Write a simple HTTP server
- Configure TLS on an HTTP server
- Send an HTTP request using fetch
- Proxy HTTP requests using fetch()
- Start a cluster of HTTP servers
- Stream a file as an HTTP Response
- fetch with unix domain sockets in Bun
- Upload files via HTTP using FormData
- Streaming HTTP Server with Async Iterators
- Streaming HTTP Server with Node.js Streams
-
Install
- Add a dependency
- Add a Git dependency
- Add a peer dependency
- Add a trusted dependency
- Add a development dependency
- Add a tarball dependency
- Add an optional dependency
- Generate a yarn-compatible lockfile
- Configuring a monorepo using workspaces
- Install a package under a different name
- Install dependencies with Bun in GitHub Actions
- Using bun install with Artifactory
- Configure git to diff Bun's lockb lockfile
- Override the default npm registry for bun install
- Using bun install with an Azure Artifacts npm registry
- Migrate from npm install to bun install
- Configure a private registry for an organization scope with bun install
-
Process
-
Read file
-
Runtime
- Delete files
- Run a Shell Command
- Import a JSON file
- Import a TOML file
- Set a time zone in Bun
- Set environment variables
- Re-map import paths
- Delete directories
- Read environment variables
- Import a HTML file as text
- Install and run Bun in GitHub Actions
- Debugging Bun with the web debugger
- Install TypeScript declarations for Bun
- Debugging Bun with the VS Code extension
- Inspect memory usage using V8 heap snapshots
- Define and replace static globals & constants
- Codesign a single-file JavaScript executable on macOS
-
Streams
- Convert a ReadableStream to JSON
- Convert a ReadableStream to a Blob
- Convert a ReadableStream to a Buffer
- Convert a ReadableStream to a string
- Convert a ReadableStream to a Uint8Array
- Convert a ReadableStream to an array of chunks
- Convert a Node.js Readable to JSON
- Convert a ReadableStream to an ArrayBuffer
- Convert a Node.js Readable to a Blob
- Convert a Node.js Readable to a string
- Convert a Node.js Readable to an Uint8Array
- Convert a Node.js Readable to an ArrayBuffer
-
Test
- Spy on methods in
bun test - Bail early with the Bun test runner
- Mock functions in
bun test - Run tests in watch mode with Bun
- Use snapshot testing in
bun test - Skip tests with the Bun test runner
- Using Testing Library with Bun
- Update snapshots in
bun test - Run your tests with the Bun test runner
- Set the system time in Bun's test runner
- Set a per-test timeout with the Bun test runner
- Migrate from Jest to Bun's test runner
- Write browser DOM tests with Bun and happy-dom
- Mark a test as a "todo" with the Bun test runner
- Re-run tests multiple times with the Bun test runner
- Generate code coverage reports with the Bun test runner
- import, require, and test Svelte components with bun test
- Set a code coverage threshold with the Bun test runner
- Spy on methods in
-
Util
- Generate a UUID
- Hash a password
- Escape an HTML string
- Get the current Bun version
- Encode and decode base64 strings
- Compress and decompress data with gzip
- Sleep for a fixed number of milliseconds
- Detect when code is executed with Bun
- Check if two objects are deeply equal
- Compress and decompress data with DEFLATE
- Get the absolute path to the current entrypoint
- Get the directory of the current file
- Check if the current file is the entrypoint
- Get the file name of the current file
- Convert a file URL to an absolute path
- Convert an absolute path to a file URL
- Get the absolute path of the current file
- Get the path to an executable bin file
-
WebSocket
-
Write file
Contributing
Refer to the Project > Contributing guide to start contributing to Bun.
License
Refer to the Project > License page for information about Bun's licensing.