feat(start): serialize Temporal types

[canac]

Since v1.6.0, seroval supports serializing Temporal types. This PR supports serializing those types in TanStack Start by extending DefaultSerializable.

Caveats

This will break on the server and/or client if the runtime doesn't support Temporal. Server environments will need a polyfill or node 26+, and client environments will need a polyfill unless they don't support Safari (caniuse). I personally think polyfills are outside the scope of a TanStack Start, but I wanted to point out that with this PR, TypeScript may accept Temporal types that the runtime does not.

Also, the temporal-polyfill dependency in e2e/react-start could be dropped by bumping the node version in .nvmrc to at least 26.0.0.

Summary by CodeRabbit

• New Features

  • Added support for serializing standard Temporal values, including dates, times, durations, and time zones.
  • Temporal data now works across server-rendered content and server-function responses.
  • Added example routes demonstrating Temporal serialization.

• Tests

  • Added end-to-end coverage validating Temporal values across SSR and server functions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4ae9a45b-7b2b-4978-9ea0-e4a136a03b50

📥 Commits

Reviewing files that changed from the base of the PR and between f97188f and 3939d21.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (12)

• .changeset/gentle-hoops-shave.md
• e2e/react-start/serialization-adapters/package.json
• e2e/react-start/serialization-adapters/src/client.tsx
• e2e/react-start/serialization-adapters/src/routeTree.gen.ts
• e2e/react-start/serialization-adapters/src/routes/index.tsx
• e2e/react-start/serialization-adapters/src/routes/server-function/temporal.tsx
• e2e/react-start/serialization-adapters/src/routes/ssr/temporal.tsx
• e2e/react-start/serialization-adapters/src/server.ts
• e2e/react-start/serialization-adapters/src/temporal-global.d.ts
• e2e/react-start/serialization-adapters/src/temporal.tsx
• e2e/react-start/serialization-adapters/tests/app.spec.ts
• packages/router-core/src/ssr/serializer/transformer.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The router serializer now includes standard Temporal instances in DefaultSerializable. The React Start serialization adapter adds Temporal polyfill setup, SSR and server-function routes, shared rendering, and end-to-end coverage.

Changes

Temporal serialization

Layer / File(s)	Summary
Temporal serializable types packages/router-core/src/ssr/serializer/transformer.ts, .changeset/gentle-hoops-shave.md	DefaultSerializable now includes standard Temporal instances resolved from globalThis. A patch changeset documents the support.
Temporal route fixtures e2e/react-start/serialization-adapters/package.json, e2e/react-start/serialization-adapters/src/*, e2e/react-start/serialization-adapters/src/routes/*	The fixture installs the Temporal polyfill, creates representative Temporal values, renders expected and returned values, and exposes SSR and server-function routes through the generated route tree.
Temporal serialization validation e2e/react-start/serialization-adapters/tests/app.spec.ts	End-to-end tests validate Temporal values from the SSR loader and server function.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: 🔵 Low · up to 3939d

The PR adds Temporal serialization and expands accepted types, but applications running without native Temporal support or a polyfill may fail at runtime. It is mergeable with explicit owner awareness that supported runtimes or polyfills are required.

Suggested labels: package: react-router, package: router-core

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant ReactStartServer
  participant TemporalRoute
  participant RouterCoreSerializer
  Browser->>ReactStartServer: Request temporal route
  ReactStartServer->>TemporalRoute: Execute loader or server function
  TemporalRoute->>RouterCoreSerializer: Serialize TemporalData
  RouterCoreSerializer-->>ReactStartServer: Return serialized Temporal values
  ReactStartServer-->>Browser: Render RenderTemporalData

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding Temporal type serialization support to TanStack Start.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	temporal-polyfill@​1.0.4

View full report