Bun 1.4's Rust Rewrite: The New Builtins, the AI-Generated Internals, and the CLAUDE.md Rules to Pin Down First (2026)

Bun 1.4 shipped on August 20, 2026, and the headline isn’t a feature — it’s that Bun rewrote its own core in Rust. About a million lines that used to be Zig are now Rust, the team says every benchmark matches or beats 1.3, the binary is roughly 20% smaller, idle CPU usage dropped by around 5x, and startup on Linux is about 50% faster. The same release also added four new builtin APIs (Bun.WebView, Bun.Image, Bun.markdown, Bun.cron) and pushed Node.js compatibility to 26.3.0. It’s a genuinely large release. It’s also one where, by the team’s own admission reported alongside launch coverage, a large share of the Rust port was AI-generated with limited manual review, and the community advice is to hold off a few point releases in production and watch WebSocket handling and native-module compatibility closely.

None of that is visible to Claude Code unless CLAUDE.md says it. An agent reading a project that pins "bun": "^1.3.0" in package.json has no way to know whether “upgrade to the latest Bun” is a routine version bump or a runtime-architecture change that happened underneath a version number that looks incremental.

Browse more real-world CLAUDE.md and AGENTS.md examples in our gallery.

What Actually Changed in 1.4

The parts worth stating explicitly in a CLAUDE.md, because none of them are visible from bun --version alone:

• Runtime rewrite — Bun’s core moved from Zig to Rust, described by the team as the first stable release running entirely on the new runtime. This is an internal implementation change, not a new major version of the public API, but it touches everything: the bundler, the transpiler, the HTTP server, the test runner.
• Performance — matches or beats 1.3 on every published benchmark, ~20% smaller binary, ~5x lower idle CPU, ~50% faster Linux startup, and a new global virtual store that the team reports makes installs up to 7x faster.
• Node.js compatibility — 26.3.0-level compatibility, with over 1,500 previously-failing Node test-suite cases now passing.
• Platform — native Windows ARM64 support, added in this release.
• Test runner — parallel test and run execution across processes, which changes timing assumptions for test suites that share state (temp files, ports, fixtures) across test files.

The Four New Builtins CLAUDE.md Should Know About

Each one replaces an npm dependency Bun projects have been reaching for since before 1.4 existed. That’s the actual leverage here — fewer node_modules, fewer supply-chain surfaces, one runtime handling what used to be three or four packages:

// Before 1.4: node-cron as a dependency
import cron from "node-cron";
cron.schedule("0 */2 * * *", () => runSync());

// 1.4+: Bun.cron, no dependency
Bun.cron("0 */2 * * *", () => runSync());

An agent that isn’t told these exist will keep reaching for the npm equivalents out of habit — they’re what’s in its training data, and they still work fine on Bun. The cost isn’t that they break; it’s an extra dependency, an extra thing to audit, for functionality the runtime now ships natively. A CLAUDE.md line naming which builtins the project has adopted (and which older npm packages they replaced) is enough to change that default.

Why “Mostly AI-Generated” Changes How Cautious CLAUDE.md Needs to Be

A rewrite of this size, generated with heavy AI assistance and reviewed less exhaustively by hand than a hand-written port would be, is a different risk profile than a normal point release — even though the version number only moved from 1.3 to 1.4. Coverage of the release specifically flags two areas to watch before trusting it in production: WebSocket handling and native-module (FFI, N-API) compatibility. Those are exactly the paths that tend to depend on subtle memory-layout and timing behavior that a benchmark suite doesn’t fully exercise.

That’s not a reason to avoid 1.4 — the performance numbers are real and the new builtins are useful today in development. It’s a reason for CLAUDE.md to draw a line between “safe to use” and “safe to auto-upgrade to,” because those aren’t the same question for this specific release.

A CLAUDE.md Template That Pins the Version and Blocks Silent Upgrades

# CLAUDE.md — Runtime

## Bun Version
- Pinned: `1.4.x` exactly (see `.bun-version` / the `packageManager` field in
  `package.json`). Do not run `bun upgrade` to move off this pin without an
  explicit, separate task — this project treats Bun version changes as
  runtime-architecture changes, not routine dependency bumps, following the
  1.3→1.4 Zig-to-Rust rewrite.
- Before bumping the pin: re-run the full test suite with
  `BUN_JSC_validateExceptionChecks=1` if the change spans a major Bun line,
  and manually exercise any WebSocket and native-module (FFI/N-API) code
  paths — these are the two areas flagged as least-tested in the 1.4 rewrite.

## Builtins In Use (prefer these over npm equivalents)
- `Bun.cron()` for scheduling — do not add `node-cron` or similar.
- `Bun.markdown` for Markdown rendering — do not add `marked` or `remark`.
- {list any of Bun.WebView / Bun.Image actually adopted, or state "not yet
  adopted" so an agent doesn't assume they're available}.

## Test Runner
- Tests run in parallel across files as of 1.4. Any test relying on a shared
  temp file, port, or external fixture must isolate it per-test (`tempDir`,
  random port via `port: 0`) — parallel execution will surface races that a
  serial runner never hit.

{
  "permissions": {
    "allow": [
      "Bash(bun --version)",
      "Bash(bun test*)",
      "Bash(bun run *)"
    ],
    "deny": [
      "Bash(bun upgrade*)",
      "Bash(bun upgrade --canary*)"
    ]
  }
}

The deny line is the one that matters most here. bun upgrade is a completely reasonable command for an agent to run on its own when a dependency issue looks version-related — it’s the standard troubleshooting move on most runtimes. For a project deliberately pinned through the 1.3→1.4 transition, that’s exactly the command that should require a human to run deliberately, not something Claude Code reaches for mid-debugging-session.

Compatibility Checklist Before Moving Off the Pin

Worth running through explicitly, not from memory, before a project actually upgrades past 1.4:

• WebSocket server and client paths tested under real load, not just a unit test that opens and closes a connection.
• Any FFI (bun:ffi) or native N-API addon rebuilt and tested against 1.4 specifically — internals moved from Zig to Rust, and ABI-adjacent code is the most likely place for that to matter.
• Test suite run with parallel execution enabled at least once, watching for races introduced by shared fixtures.
• bun.lock regenerated and diffed, given the new global virtual store changes how installs resolve.
• Windows CI (if any) re-verified separately if the project runs on ARM64 — this is new platform support, not a compatibility carry-over.

What Bun’s Own AGENTS.md Covers (and Doesn’t)

Bun publishes an AGENTS.md for contributing to the Bun repository itself — build commands, test organization, the Zig/C++/TypeScript source layout. It’s genuinely useful if you’re patching Bun’s runtime, and it’s a different document from what a project using Bun needs:

Third-party Bun skills on the Claude Code marketplaces run into the same gap from a different angle — they teach Bun.serve(), Bun.file(), Bun.$, and general Bun-over-Node.js API preferences, which is useful and mostly version-independent. None of the ones we reviewed address which Bun version a project is actually pinned to, or that 1.4 specifically warrants extra caution before an autonomous upgrade. That’s context only the project’s own CLAUDE.md can carry, because it depends on when the project adopted 1.4, not on how Bun’s APIs work in general.

Common Mistakes to Watch For

Letting an agent run bun upgrade as a routine troubleshooting step. It’s a reasonable instinct on most runtimes and the wrong one for a project deliberately holding at a specific 1.4.x point release — deny it explicitly rather than relying on the agent to infer caution from a version number.

Adding node-cron, marked, or sharp out of habit on a project already on 1.4. The builtins exist and remove a dependency; an agent only avoids the npm install if CLAUDE.md says the builtin is the house standard.

Assuming a WebSocket bug is application code because “the runtime just does WebSockets.” 1.4’s WebSocket path is one of the two areas explicitly flagged as less exhaustively tested in the rewrite — worth ruling out before spending time in application-level logic.

Treating Bun’s own AGENTS.md as coverage for “using Bun” questions. It documents contributing to Bun’s source tree, not the version-pinning and builtin-adoption decisions a consuming project needs to make.

The Rust rewrite is a good release — faster, smaller, fewer dependencies needed for common tasks. The part that needs writing down isn’t whether to use 1.4, it’s that this particular version bump changed more under the hood than the version number implies, and that’s exactly the kind of thing a coding agent has no way to know unless the project’s own CLAUDE.md tells it.

Browse more real-world CLAUDE.md and AGENTS.md examples in our gallery.

FAQ

Is Bun 1.4 safe to use in production? The performance numbers are real and match or beat 1.3 on every published benchmark, but a large share of the Rust rewrite was AI-generated with less exhaustive manual review than a hand-written port, and community guidance is to hold off a few point releases and specifically verify WebSocket handling and native-module (FFI/N-API) compatibility before relying on it in production.

What changed under the hood in Bun 1.4? Roughly a million lines of Bun’s core moved from Zig to Rust — described as the first stable release running entirely on the new runtime. The public API didn’t change; the internal implementation of the bundler, transpiler, HTTP server, and test runner did.

What are Bun 1.4’s new builtin APIs? Bun.WebView (headless browser automation, replacing Puppeteer/Playwright for many uses), Bun.Image (image processing, replacing sharp), Bun.markdown (Markdown parsing, replacing marked/remark), and Bun.cron() (job scheduling, replacing node-cron).

Does Bun’s own AGENTS.md cover how to use Bun in my project? No. Bun publishes an AGENTS.md for contributing to Bun’s own source code — build commands, test organization, the Zig/C++/TypeScript layout of the Bun repository itself. It doesn’t address which Bun version a consuming project should pin or how to adopt the 1.4 builtins.

Should CLAUDE.md block Claude Code from running bun upgrade? For a project deliberately pinned through the 1.3-to-1.4 transition, yes — bun upgrade is a reasonable default troubleshooting move on most runtimes, which is exactly why it needs an explicit deny in settings.json rather than relying on the agent to infer that this particular upgrade needs a human decision.