Unverified Commit 526c492a authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: document React browser API (#97621)

### What?

- Documents React Canary's new `browser` API in the SPA guide
- Adds examples for marking a Client Component as browser-only and
wrapping it in Suspense

### Why?

The App Router includes React Canary releases, and the `browser` API now
provides a Suspense-based option for components that depend on browser
APIs such as `window` or `document`.

### How?

The guide calls `browser()` inside `use()` in a Client Component. It
then wraps that component in Suspense so prerendering can show the
closest fallback before the component renders in the browser.

### Testing

- `prettier --check docs/01-app/02-guides/single-page-applications.mdx`
- `alex docs/01-app/02-guides/single-page-applications.mdx --quiet`
(only existing SPA dictionary warnings)
parent 67f42155
...@@ -216,7 +216,51 @@ const ClientOnlyComponent = dynamic(() => import('./component'), { ...@@ -216,7 +216,51 @@ const ClientOnlyComponent = dynamic(() => import('./component'), {
This can be useful for third-party libraries that rely on browser APIs like `window` or `document`. You can also add a `useEffect` that checks for the existence of these APIs, and if they do not exist, return `null` or a loading state which would be prerendered. This can be useful for third-party libraries that rely on browser APIs like `window` or `document`. You can also add a `useEffect` that checks for the existence of these APIs, and if they do not exist, return `null` or a loading state which would be prerendered.
See the [live demo](https://next-spa-patterns.labs.vercel.dev/browser-only) and its [source code](https://github.com/vercel-labs/next-spa-patterns/tree/main/app/browser-only). React 19.3 includes the [`browser`](https://react.dev/reference/react-dom/browser) API. Use `use(browser())` only when a Client Component's first browser render cannot match server-rendered HTML.
During prerendering, `use(browser())` suspends to the closest `<Suspense>` boundary. The fallback becomes the component's initial HTML, so crawlers that don't execute JavaScript see the fallback instead of the component. Keep content that should be indexed outside the browser-only boundary.
For example, this editor reads a saved draft from `localStorage`:
```jsx filename="app/browser-only-editor.jsx"
'use client'
import { use, useState } from 'react'
import { browser } from 'react-dom'
export default function BrowserOnlyEditor() {
use(browser('The saved draft is stored in localStorage.'))
const [draft, setDraft] = useState(() => localStorage.getItem('draft') ?? '')
function handleChange(event) {
const nextDraft = event.target.value
setDraft(nextDraft)
localStorage.setItem('draft', nextDraft)
}
return <textarea value={draft} onChange={handleChange} />
}
```
Then wrap it in a Suspense boundary:
```jsx filename="app/page.jsx"
import { Suspense } from 'react'
import BrowserOnlyEditor from './browser-only-editor'
export default function Page() {
return (
<Suspense fallback={<p>Loading editor…</p>}>
<BrowserOnlyEditor />
</Suspense>
)
}
```
In the browser, `browser()` returns `undefined`, and the editor renders with the saved draft.
See both approaches in the [live demo](https://next-spa-patterns.labs.vercel.dev/browser-only). The [demo source](https://github.com/vercel-labs/next-spa-patterns/tree/main/app/browser-only) contains the complete examples.
### Shallow routing on the client ### Shallow routing on the client
......
...@@ -47,7 +47,7 @@ You can find the resources used in this example here: ...@@ -47,7 +47,7 @@ You can find the resources used in this example here:
- [Demo](https://react-view-transitions-demo.labs.vercel.dev) - [Demo](https://react-view-transitions-demo.labs.vercel.dev)
- [Code](https://github.com/vercel-labs/react-view-transitions-demo) - [Code](https://github.com/vercel-labs/react-view-transitions-demo)
View transitions work in the App Router with no configuration. The App Router uses [React canary releases](https://react.dev/blog/2023/05/03/react-canaries), which contain all stable React 19 changes as well as newer features like `ViewTransition`. You do not need to install `react@canary` yourself. View transitions work in the App Router with no configuration. React 19.3 includes the `<ViewTransition>` component and `addTransitionType` API used in this guide.
> [!NOTE] > [!NOTE]
> React's integration uses newer View Transitions API features (transition types and `view-transition-class`), available in Chromium 125+ and recent Safari and Firefox versions. Some animations may behave differently in Safari. Without browser support, your application works normally; the transitions do not animate. > React's integration uses newer View Transitions API features (transition types and `view-transition-class`), available in Chromium 125+ and recent Safari and Firefox versions. Some animations may behave differently in Safari. Without browser support, your application works normally; the transitions do not animate.
......
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