Which layer should own timezone conversion in Vue 3 SSR hydration?

The Optimal Layer for Timezone Conversion

Timezone conversion should be owned by a centralized state store (such as Pinia). This ensures a single source of truth for the user's target timezone across both the server and client, preventing the inconsistent state that leads to hydration mismatches.

Explanation of Layering and Hydration

Hydration mismatches occur when the server renders a date based on its system clock (often UTC) and the client attempts to render the same date based on the browser's local timezone. Because Vue 3 compares the server-generated HTML with the first client-side render, any difference in the resulting string triggers a warning.

• Individual Components: Performing conversion here is risky. If a component uses new Date() or a library like Luxon without a forced zone, it will use the environment's local time, almost guaranteeing a mismatch.
• Global Plugins: These are useful for providing the context (the IANA zone string), but the actual transformation logic should be tied to the state that drives the UI.
• Pinia Store: By storing the target timezone in a store, the server can be instructed to render in a specific zone (via headers or user preferences), and the client can hydrate that same state, ensuring the initial render matches the server HTML.

Implementation Steps

1. Transport ISO 8601: Always pass dates from the API to the frontend as ISO 8601 strings. Do not pass pre-formatted date strings from the server.
2. Centralize the Zone: Store the user's IANA timezone string (e.g., America/New_York) in a Pinia store.
3. Force the Zone: Use a library like Luxon or date-fns-tz to format the date by explicitly passing the zone from the store, rather than relying on the system default.
4. Consistent Rendering: Ensure the server has access to the user's timezone (via a cookie or request header) so it can render the correct local time before sending the HTML to the client.

SEO and Client-Only Components

Deferring formatting to <ClientOnly> components or the onMounted hook does avoid hydration mismatches, but it harms SEO. Because the date content is missing from the initial HTML source, search engine crawlers may not index the dates or may see them as empty placeholders. To preserve SEO, you must ensure the server renders the correct timezone-aware string.

Verification

To verify the implementation, perform the following checks:

• Source Comparison: Right-click and "View Page Source" to see the server HTML, then "Inspect Element" to see the hydrated DOM. The date strings must be identical.
• Console Audit: Check the browser console for Hydration completed but contains mismatches warnings.
• Cross-Zone Testing: Change your system clock's timezone and reload the page; the rendered date should remain consistent with the user's account settings, not the system clock.

Diagnostic Detail Needed: Are you currently determining the user's timezone via a request header (server-side) or via Intl.DateTimeFormat().resolvedOptions().timeZone (client-side)? This determines whether the server can actually render the correct zone for the first paint.