docs: add Bun 1.3 to 1.4 upgrade guide

[robobun]

Adds docs/upgrade-to-1.4.mdx, a migration reference for the user-visible behavior changes between Bun 1.3.14 and Bun 1.4, linked from the "Get Started" navigation group and from the existing bun upgrade guide. Also updates docs/installation.mdx and docs/bundler/executables.mdx so the CPU-requirement and cross-compile-target docs agree with the single-x64-build change the guide describes.

The page is the "what do I change" companion to the tracking list at #28792: each section states what changed, who is affected, and the one-line fix, with code examples for the items that need one.

Rebased on current main and re-audited against both #28792 and git log for the commits that landed since the guide was first written; the second table below is what that added.

Covered with dedicated sections (original audit)

Change	Source
bun.lock written as lockfileVersion: 2 for new lockfiles	#31539
trustedDependencies matches resolved name, not alias; hash-only / non-canonical entries no longer trusted	#31175, #31218, #31339
Strict TOML parsing; inf/nan are numbers, integers outside safe range throw, errors are SyntaxError	#32953
tsconfig "jsx": "react-jsx" emits the production JSX runtime	#34422
Bun.cron schedules interpreted in local time; { tz } option added	#35122
Bun Shell: glob metacharacters in interpolated values are literal; ambiguous redirect	#31220, #34324
CSS default import at runtime is {} (matches bun build)	#35163
process.versions.node is 26.3.0; writeHeader removed, stream.read() one-chunk, dgram sync throws	#31991, #33037, #33024
fetch / Bun.serve combine duplicate wire headers; clone() throws on disturbed body; Response.redirect parses URL; truncated compressed body rejects; option-conversion errors reject	#31734, #33129, #33126, #34922, #33649
Bun.Socket#setKeepAlive delay is milliseconds	#34269
MySQL DATETIME / TIMESTAMP decode as UTC	#31212
Single x64 build; -baseline names are aliases	#34782

Added in the refresh (landed on main after the first revision)

Change	Source
Optional-peer-only packages dropped from existing lockfiles on first install (--frozen-lockfile implication); nested npm: alias no longer redirected to a root alias; bun update <name> re-resolves every occurrence	#35681, #33835, #36360, #36379
tsconfig useDefineForClassFields: false is honored	#36664
.env files not auto-loaded when Bun is invoked as node	#36610
Bun.serve HTML routes: no sourcemaps in production, [serve.static] sourcemap override	#36982
server.stop() closes idle connections and waits for all connections; stop(true) after stop() force-closes	#35130, #37074
.xml default loader	#37048
process.env coerces to string / defineProperty validation; default "warning" listener registered at startup; process.title default	#31831, #37344
node:dns.lookup() uses the system resolver on Linux	#37383
new URL() error message / ERR_INVALID_URL; assert.deepStrictEqual prototype + own-property parity; callback throws surface as uncaughtException	#34660
node:http writeHead() + end(chunk) sends chunked, maxConnections enforced; node:cluster / IPC internalMessage; worker_threads exit semantics; recursive fs.watch errors	#34432, #31829, #37075, #36415
Temporal enabled by default (BUN_JSC_useTemporal=0 to disable)	#32978
MariaDB json columns parsed	#37130
Postgres honors PGSSLMODE	#36840
bun:sqlite close() finalizes query() statements; LRU cache	#36573, #36793
HTMLRewriter streams; string input with async handler throws; error routing	#36733
Client WebSocket close event is a queued task (CLOSING state)	#27259
Cyclic Array.prototype.join() throws RangeError (JSC update)	#36794
Bun.JSONC.parse SyntaxError; S3 XML entity decoding / InvalidResponse; Transfer-Encoding 400; per-serverName requestCert; fetch TLS session cache flag; udpSocket / password / RedisClient#expire / openInEditor validation; browser field honored for polyfills	#35066, #37194, #35295, #36174, #36598, #36999, #36835, #37210, #36597

Also corrected in the refresh: the runtime note about .module.css (it follows the same {} rule as plain .css under bun run; only bun build produces the class map).

installation.mdx and bundler/executables.mdx

These pages still described a separate AVX2 build with a "baseline is slower" fallback, contradicting #34782 and the new guide they sit next to in the nav. Updated to one x64 download / target per platform, a one-row CPU table (SSE4.2 / Nehalem), and notes that the -baseline / -modern names are aliases.

Why

There is no existing page that collects the 1.4 behavior changes in one place. A single reference page at a stable URL is what support threads and the release post can link to. The page lives at the docs root alongside /typescript-6 (the existing version-change page) and is surfaced in the "Get Started" navigation group alongside /installation.

Verification

• Every claim in the refresh was checked against the PR body or the current source (for example version_to_write() in bun.lock.rs, normalizeSSLMode in sql/shared.ts, the webkit-upgrade-3722912f pinning test, docs/runtime/networking/dns.mdx for the backend option).
• Every internal link resolves to an existing page / anchor; docs/docs.json validates; prettier --check passes on all changed files; MDX tag balance and fence parity checked.

Docs-only change; no native code touched.

Related: #28792 (does not close it; that issue still has open "under consideration" items, and several of the refresh items above are not yet listed there).

---

no test proof · iteration 0 · docs-only change; test-proof not applicable

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 16 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: c0eca598-795c-4d8d-b06a-5e07f879b52b

📥 Commits

Reviewing files that changed from the base of the PR and between 165dc9f and a5a9096.

📒 Files selected for processing (5)

• docs/bundler/executables.mdx
• docs/docs.json
• docs/guides/util/upgrade.mdx
• docs/installation.mdx
• docs/upgrade-to-1.4.mdx

Walkthrough

Changes

Bun 1.4 documentation

Layer / File(s)	Summary
Distribution and executable targets docs/bundler/executables.mdx, docs/installation.mdx, docs/upgrade-to-1.4.mdx	Executable targets, download options, CPU requirements, and baseline alias behavior now describe standard x64 builds.
Upgrade guide entry and core behavior changes docs/docs.json, docs/guides/util/upgrade.mdx, docs/upgrade-to-1.4.mdx	Adds the upgrade guide to navigation and documents Bun 1.4 changes to lockfiles, dependency trust matching, TOML, JSX, cron, shell interpolation, and CSS imports.
Runtime compatibility and migration details docs/upgrade-to-1.4.mdx	Documents Node, Fetch, networking, database, validation, and CLI changes, along with instructions for pinning to Bun 1.3.

Possibly related issues

• List of breaking changes for 1.4 #28792 — Tracks the same Bun 1.4 breaking changes documented by this PR.

Possibly related PRs

• oven-sh/bun#34782 — Implements the baseline artifact and alias behavior that these documentation updates describe.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely identifies the main change: adding a Bun 1.3-to-1.4 upgrade guide.
Description check	✅ Passed	The description explains the changes, rationale, scope, related issue, and verification steps in sufficient detail.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Found 1 issue this PR may fix:

1. List of breaking changes for 1.4 #28792 - The upgrade guide documents all merged 1.4 breaking changes, fulfilling this tracking issue's purpose of listing user-visible behavior changes

If this is helpful, copy the block below into the PR description to auto-close these issues on merge.

Fixes #28792

🤖 Generated with Claude Code

[robobun]

^{Updated 3:41 PM PT - Aug 12th, 2026}

✅ @robobun, your commit a5a909642eff1885d915e4a12252a1591fc14ef5 passed in Build #93659! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 36463

That installs a local version of the PR into your bun-36463 executable, so you can run:

bun-36463 --bun

[claude]

LGTM — all five prior accuracy notes are addressed in the current diff and this run's bug hunt found nothing new.

What was reviewed:

• Confirmed the five earlier fixes landed: bunfig TOML error format/redaction, lockfile v0→v1 wording, CSS-modules link target, client-only WebSocket#close() scoping, and the JSX cross-reference.
• docs.json nav entry and internal links (/pm/lifecycle, /runtime/toml, /runtime/jsx, /runtime/cron, /runtime/shell, /bundler/css#css-modules, /guides/util/upgrade) resolve.
• installation.mdx / executables.mdx baseline-build removals are consistent with each other and with the new guide's single-x64-build section.

Extended reasoning...

Overview

Docs-only PR: adds docs/upgrade-to-1.4.mdx (~310 lines) as a 1.3→1.4 migration reference, wires it into the "Get Started" nav group in docs.json, links it from guides/util/upgrade.mdx, and updates installation.mdx and bundler/executables.mdx to drop the separate AVX2/baseline x64 build language so those pages agree with the new guide. No source, test, or build files are touched.

Security risks

None. This is prose and MDX markup with no executable code, no secrets, and no changes to auth/crypto/permissions paths.

Level of scrutiny

Medium — the risk here is factual accuracy across ~30 behavior-change claims, not code correctness. That risk was actively exercised: two prior review rounds surfaced five accuracy issues (TOML error format for bunfig, lockfile v0 handling, CSS-modules link target, server-vs-client WebSocket close() validation, and a JSX cross-reference that overpromised), and all five were fixed in 645a3cb and 31351fe. This run's bug-hunting pass found nothing further. Each headline claim in the page maps to a referenced PR in the description, and the neighboring pages (installation.mdx, executables.mdx) were updated in the same PR so they don't contradict the new guide.

Other factors

• All prior inline threads are resolved; the current diff reflects every requested wording change verbatim.
• MDX tag balance / code-fence parity looks correct in the preloaded content; docs.json remains valid JSON with the single added array entry.
• The page sits alongside /typescript-6 (the existing version-change page), so nav placement follows an established pattern.
• Docs-only, so any residual wording nit is trivially correctable post-merge with no user-facing breakage.

[alii]

@robobun Get this up to date since things might have changed in the past two weeks

[robobun]

Rebased onto current main (c371e3a) and re-audited the ~350 commits that landed since the first revision, against both #28792 and git log. Nothing already in the guide was reverted; the refresh adds the changes that landed in the meantime, the larger ones being:

• useDefineForClassFields: false now honored (js_parser: honor tsconfig useDefineForClassFields: false #36664)
• .env files not auto-loaded when Bun runs as node (cli: skip automatic .env loading when invoked as node #36610)
• Bun.serve HTML routes stop serving sourcemaps in production, [serve.static] sourcemap override (Bun.serve: don't serve sourcemaps for HTML routes in production #36982); server.stop() now closes idle connections (Bun.serve: gate the graceful stop() drain promise on open connections #35130, Bun.serve: close idle connections on graceful stop(), declare closeIdleConnections() #37074)
• .xml default loader (Add Bun.XML (parse/stringify) and an .xml loader #37048)
• process.env string coercion and the default "warning" listener (process: port Node.js v26.3.0 process compatibility tests and fix the gaps they surface (env exotic-object/TZ semantics, warnings pipeline + CLI flags, uncaught origin/exit codes, execve throw, threadCpuUsage/finalization/loadEnvFile, native-module identity; +26 tests) #31831, process: register the default 'warning' listener at process creation, like Node #37344)
• node:dns.lookup() on the system resolver for Linux (node:dns: use the system resolver for dns.lookup #37383)
• new URL() message / assert.deepStrictEqual parity (node compat batch: callback-throw dispatch, Assert class + native deep-equality parity, Intl gate + URL/buffer fallout, compile cache, watch kill-signal, profilers (+98 tests) #34660)
• Temporal on by default (Enable Temporal by default #32978)
• MariaDB JSON columns (sql(mysql): negotiate MariaDB extended type info so JSON columns parse into objects #37130), PGSSLMODE (sql(postgres): honour PGSSLMODE from the environment #36840), bun:sqlite close() (bun:sqlite: finalize outstanding prepared statements on close via sqlite3_next_stmt #36573, bun:sqlite: keep close(false) graceful for prepare() statements, make query() cache LRU #36793)
• HTMLRewriter streaming (HTMLRewriter: stream through SinkHandle/SourceHandle; suspend async handlers instead of wait_for_promise #36733)
• optional-peer lockfile cleanup and its --frozen-lockfile implication (install: drop packages held only by optional-peer resolution slots from bun.lock #35681)

Full list with sources is in the PR description. Also corrected the runtime .module.css note. Several of these are not yet on #28792 if you want to sync that list.

[claude]

I reviewed the latest revision and found no issues — commit a5a9096 addresses the last open nit (assert.strictEqual dropped from the deep-equality bullet), and all earlier feedback has been incorporated. Given this is the release-facing 1.4 upgrade guide with factual claims spanning the package manager, bundler, runtime, SQL drivers, and Node compat, a maintainer read-through before publishing is still worthwhile.

What was reviewed

• Confirmed the six prior nits (TOML error format, lockfile v0→v1, CSS Modules link, WebSocket close() scope, JSX cross-reference, assert.strictEqual) are all fixed in the current diff.
• Checked docs.json nav entry, internal link targets, and MDX tag balance in the new page.
• Verified the installation.mdx / executables.mdx CPU-requirement edits are internally consistent with the single-x64-build section.

Extended reasoning...

Overview

This PR adds docs/upgrade-to-1.4.mdx (482 lines), a comprehensive migration guide covering ~40 behavior changes between Bun 1.3 and 1.4, and updates docs/installation.mdx, docs/bundler/executables.mdx, docs/docs.json, and docs/guides/util/upgrade.mdx to align with the single-x64-build change and link the new page. It is docs-only; no runtime code is touched.

Security risks

None. Pure documentation; no code paths, no build configuration, no dependencies.

Level of scrutiny

Higher than a typical docs change. This is the canonical upgrade guide for a major release — it will be linked from the release post and support threads, and each of its ~40 sections makes a specific technical claim about runtime behavior. Earlier review rounds surfaced six factual inaccuracies (all now fixed), which suggests the density of claims warrants a human editorial pass rather than auto-approval. The refresh commit (c371e3a) also added ~15 new sections covering changes that landed after the original draft; a maintainer requested that refresh but has not yet reviewed the result.

Other factors

• All prior automated feedback has been addressed across five commits; the last inline comment (assert.strictEqual) is fixed in a5a9096, and the current diff reflects that.
• CI passed on the head commit.
• The nav placement (Get Started group, alongside /typescript-6) and the editorial scope of what to include vs. defer to #28792 are product decisions a maintainer should sign off on.
• No CODEOWNERS file governs docs/, but release documentation is high-visibility content.