Unverified Commit 931868b8 authored by Jimmy Lai's avatar Jimmy Lai Committed by GitHub

docs: add guide for displaying dates without hydration flash (#92786)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
### What?

Adds a new documentation guide at
`docs/01-app/02-guides/displaying-dates.mdx` that documents how to
display locale-aware dates and times on prerendered/static pages without
a visible flash when the page loads.

### Why?

Dates and times formatted with `toLocaleDateString()` or
`Intl.DateTimeFormat` produce different output on the server (build-time
locale/timezone) vs the browser (user's locale/timezone). On prerendered
pages this causes a visible text change ("snap") when React hydrates and
re-renders with the correct locale.

There was no existing documentation for this common pattern. The inline
script approach (running a small `<script>` synchronously before browser
paint to correct the DOM) is the recommended technique for static/cached
pages.

### How?

**New guide** (`displaying-dates.mdx`) follows the progressive example
style from `public-static-pages.mdx`:

1. **Step 1**: Shows the problem — a static page with a server-formatted
date
2. **Step 2**: Fixes it with an inline `<script>` +
`suppressHydrationWarning`
3. **Step 3**: Extracts a reusable `<LocalDate>` component with `<time>`
element for accessibility/SEO

Also includes a comparison table for when to use alternative approaches
(`connection()`, Client Components with `useEffect`, fully dynamic
pages).

**Cross-references added:**
- `public-static-pages.mdx` — callout in the "Static components" section
where "the current time" is mentioned
- `connection.mdx` — callout noting the inline script alternative for
prerendered pages

### Improving Documentation

- Ran `prettier` to fix formatting
- Follows doc conventions (frontmatter, `switcher` pattern, `filename`
attributes, callout format)

<!-- NEXT_JS_LLM_PR -->
<!-- CURSOR_AGENT_PR_BODY_END -->

[Slack
Thread](https://vercel.slack.com/archives/C03S8ED1DKM/p1776095579605699?thread_ts=1776095579.605699&cid=C03S8ED1DKM)

<div><a
href="https://cursor.com/agents/bc-e7710133-5c01-4a8a-9147-1ccbc9b6dd89"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-e7710133-5c01-4a8a-9147-1ccbc9b6dd89"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------
Co-authored-by: 's avatarCursor Agent <cursoragent@cursor.com>
Co-authored-by: 's avatarJoseph Chamochumbi <joseph.chamochumbi@vercel.com>
parent a03b8eee
This diff is collapsed.
...@@ -45,6 +45,8 @@ export default async function Page() { ...@@ -45,6 +45,8 @@ export default async function Page() {
The `<Header />` component doesn't depend on any inputs that change between requests, such as: external data, request headers, route params, the current time, or random values. The `<Header />` component doesn't depend on any inputs that change between requests, such as: external data, request headers, route params, the current time, or random values.
> **Good to know**: If you need to display locale-aware dates or times without a visible flash, see [Preventing flash before hydration](/docs/app/guides/preventing-flash-before-hydration).
Since its output never changes and can be determined ahead of time, this kind of component is called a **static** component. With no reason to wait for a request, Next.js can safely **prerender** the page at [build time](/docs/app/glossary#build-time). Since its output never changes and can be determined ahead of time, this kind of component is called a **static** component. With no reason to wait for a request, Next.js can safely **prerender** the page at [build time](/docs/app/glossary#build-time).
We can confirm this by running [`next build`](/docs/app/api-reference/cli/next#next-build-options). We can confirm this by running [`next build`](/docs/app/api-reference/cli/next#next-build-options).
......
...@@ -788,3 +788,4 @@ The key decisions are **what to cache** and **where to place Suspense boundaries ...@@ -788,3 +788,4 @@ The key decisions are **what to cache** and **where to place Suspense boundaries
- [Streams API on web.dev](https://web.dev/articles/streams) - introduction to the Web Streams API that underpins streaming in Route Handlers - [Streams API on web.dev](https://web.dev/articles/streams) - introduction to the Web Streams API that underpins streaming in Route Handlers
- [Chunked transfer encoding (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Transfer-Encoding) - the HTTP/1.1 mechanism that enables streaming responses - [Chunked transfer encoding (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Transfer-Encoding) - the HTTP/1.1 mechanism that enables streaming responses
- [browser.engineering](https://browser.engineering/) - deep dive into how browsers handle network responses, rendering, and progressive display - [browser.engineering](https://browser.engineering/) - deep dive into how browsers handle network responses, rendering, and progressive display
- [Preventing flash before hydration](/docs/app/guides/preventing-flash-before-hydration) - how to update server-rendered HTML with client-specific values (locale, theme, persisted state) before the browser paints
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment