docs: TOML date/time values in bundles compile to Temporal calls

[robobun]

Problem

• Since TOML: map date/time values to Temporal, round-trip them through stringify #37018, the TOML loader compiles date/time values to Temporal.<Class>.from("...") calls in bun build output. The emit does not depend on target (lower_toml_datetimes is set from the loader alone in src/js_parser/parse/parse_entry.rs).
• A bundle built with --target=node or --target=browser from a TOML file containing a date therefore throws ReferenceError: Temporal is not defined at load on a runtime without Temporal (Node.js 24 and earlier, for example).
• Neither docs/runtime/toml.mdx (Bundler Integration) nor the toml entry in docs/bundler/loaders.mdx mentioned this; the runtime docs only describe the Bun.TOML.parse / import mapping.

Fix

• docs/runtime/toml.mdx: new "Date and time values in bundles" section under Bundler Integration showing the emitted code and the three ways to run such a bundle on a runtime without Temporal (named imports so the date keys tree-shake, quoting the value, or importing a module that installs a global Temporal ahead of the TOML file).
• docs/bundler/loaders.mdx: one note in the toml loader entry linking to that section.
• Docs only; no code change. The heading uses plain words so the anchor in the cross-link is unambiguous.
• Every claim was checked against a debug build of main (88a6398836):
  • bun build app.ts --target=browser and --target=node both emit released: /* @__PURE__ */ Temporal.PlainDate.from("2026-08-15") for released = 2026-08-15.
  • node out.js (Node 26, Temporal enabled) prints the date; node --no-harmony-temporal out.js throws ReferenceError: Temporal is not defined.
  • import { name } from "./config.toml" bundles to var name = "my-app"; with no Temporal reference.
  • A module assigning globalThis.Temporal, imported before the TOML file, precedes the TOML module in the bundle and the bundle runs under node --no-harmony-temporal.
  • prettier --check passes on both files.

Background

• Bun's TOML loader turns a .toml file into a JS module whose exports are the parsed document. At runtime (import / Bun.TOML.parse) date/time values are built as Temporal objects directly. In the bundler the same values have to be expressed as JavaScript source, so the parser rewrites each tagged date/time string into a call on the Temporal global; that call runs when the bundle's module-scope code evaluates, which is why the consuming runtime needs Temporal.
• Bun enables Temporal by default as of 1.4, so this only matters for bundles run elsewhere. The parser rewrite itself (Rewrite the TOML parser for v1.1.0 conformance #32953) and the integer range rule are already documented on the same page and in the 1.4 upgrade guide (docs: add Bun 1.3 to 1.4 upgrade guide #36463); this PR only fills the bundler gap.

---

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: 1 minute

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: be00125f-e0c1-45e9-8142-8744f8bfe4a9

📥 Commits

Reviewing files that changed from the base of the PR and between 88a6398 and b981102.

📒 Files selected for processing (2)

• docs/bundler/loaders.mdx
• docs/runtime/toml.mdx

---

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

[robobun]

^{Updated 9:56 AM PT - Aug 15th, 2026}

✅ @robobun, your commit b98110242c1aa243e21f40c7d70a4b5afe9da452 passed in Build #98335! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 39120

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

bun-39120 --bun

[robobun]

Status: docs-only, CI green (Format, Lint, Buildkite #98335), no review findings to address. Ready for a maintainer.

• Origin: a 1.3.14 vs 1.4 comparison of the TOML loader. The parser changes themselves (Rewrite the TOML parser for v1.1.0 conformance #32953) are intentional and already documented; the one gap was that bun build output for a TOML date/time value now references the Temporal global for every target (TOML: map date/time values to Temporal, round-trip them through stringify #37018), which the bundler docs did not mention.
• Verified against a debug build of main (88a6398836): --target=browser and --target=node both emit Temporal.PlainDate.from("2026-08-15"); the bundle runs under Node 26 and throws ReferenceError: Temporal is not defined under node --no-harmony-temporal; each of the three workarounds listed in the new section was run the same way.
• prettier --check passes on both files.

[claude]

LGTM — docs-only addition documenting that bundled TOML date/time values compile to Temporal.*.from() calls.

What was reviewed:

• Verified against src/js_parser/parse/parse_entry.rs: lower_toml_datetimes is set from loader == Loader::Toml alone (not target-gated), and the lowering emits Temporal.<class>.from(...) with CallUnwrap::IfUnused (the @__PURE__ annotation), matching the example output and the tree-shaking claim.
• Cross-link anchor /runtime/toml#date-and-time-values-in-bundles matches the new ### heading slug and follows the existing link convention in docs/.
• <Note> component and code-fence labels match neighboring usage in both files.

Extended reasoning...

Overview

Two docs files touched: docs/runtime/toml.mdx gains a new ### Date and time values in bundles subsection under Bundler Integration (a TOML+JS example plus three workarounds for runtimes without Temporal), and docs/bundler/loaders.mdx gains a three-line <Note> in the toml loader entry linking to it. No source, test, or config changes.

Security risks

None. Pure prose and fenced code examples in .mdx files; nothing is executed or exposed.

Level of scrutiny

Low. Docs-only, ~25 net lines. I spot-checked the technical claims against the parser: parse_entry.rs:297 sets lower_toml_datetimes purely from the loader (confirming "for every target"), and lower_one_date_time_literal builds Temporal.<class>.from(str) with can_be_unwrapped_if_unused = IfUnused, which is what the printer renders as /* @__PURE__ */ — so the emitted-output snippet and the named-import tree-shaking workaround are both accurate. The Node.js version statement (24 and earlier lack Temporal by default) is correct.

Other factors

CI (Build #98335) is green, prettier passes per the PR description, no CODEOWNERS covers docs/, and there are no prior human review comments to address. The cross-link path style (/runtime/toml#anchor) matches other internal links in the docs tree. The <Note> component is already used a few lines above in the same file for the jsonc loader, so the MDX is consistent.