tRPC Date Serialization Shift from ISO Strings to Unix Timestamps in v11

Recommendation

If your application requires the preservation of original timezone offsets or must maintain backward compatibility with v10 clients, you should adopt a custom transformer or configure your serializer to restore ISO-8601 strings. While Unix timestamps are efficient, they represent a UTC instant and discard the sender's local offset, which can lead to "hour-shift" errors in UI displays if the client assumes a local timezone that differs from the server's intended context.

Analysis of Serialization Behavior

tRPC does not handle serialization natively; it delegates this to transformers like superjson. The shift from ISO-8601 strings to numeric timestamps changes the underlying JSON type from a string to a number. Because JSON does not have a native Date type, this change is a breaking API contract modification.

Confirmed Facts

• Data Loss: Unix timestamps are UTC-based. Any timezone offset information present in an ISO-8601 string (e.g., +05:30) is lost during conversion to a timestamp.
• Client Breaking Changes: Clients expecting a string for Date parsing will fail or produce Invalid Date when receiving a number if the transformer versions are mismatched.
• UTC Assumption: Using timestamps assumes all participating systems treat the value as a UTC instant.

Implementation Steps for ISO-8601 Restoration

1. Define a Custom Transformer: Create a transformer wrapper that explicitly calls .toISOString() during serialization and new Date() during deserialization.
2. Update Server Configuration: Replace the default superjson transformer in your tRPC initialization with your custom implementation.
3. Synchronized Deployment: Deploy the server and client updates simultaneously. Because the data format changes, a staggered rollout will cause runtime errors for clients receiving the "wrong" type.

Verification Process

To confirm the serialization format and ensure no offset errors are introduced, use the following scoped verification steps:

• Network Inspection: Open the Browser Developer Tools > Network Tab. Inspect the raw JSON response. A timestamp appears as a number (e.g., 1728850000), while ISO-8601 appears as a string (e.g., "2026-10-14T06:33:45.000Z").
• Value Comparison: Compare the server-side Date object with the client-side result:

  console.log(new Date(receivedValue).toISOString() === originalServerIsoString);

Missing Diagnostic: To provide a more specific transformer implementation, please clarify if you are using a monorepo (where server/client types are shared) or separate repositories, as this changes the deployment strategy for the migration.