Unverified Commit 5cf76223 authored by Joseph's avatar Joseph Committed by GitHub

docs: Improve troubleshooting and awareness around useSearchParams (#83226)

Closes: https://linear.app/vercel/issue/DOC-5030/usesearchparams
parent 50d5a0a7
...@@ -3,7 +3,11 @@ title: Route Segment Config ...@@ -3,7 +3,11 @@ title: Route Segment Config
description: Learn about how to configure options for Next.js route segments. description: Learn about how to configure options for Next.js route segments.
--- ---
> The options outlined on this page are disabled if the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) flag is on, and will eventually be deprecated in the future. > **Good to know**:
>
> - The options outlined on this page are disabled if the [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) flag is on, and will eventually be deprecated in the future.
> - Route Segment options only take effect in Server Component Pages, Layouts, or Route Handlers.
> - `generateStaticParams` cannot be used inside a `'use client'` file.
The Route Segment options allows you to configure the behavior of a [Page](/docs/app/api-reference/file-conventions/layout), [Layout](/docs/app/api-reference/file-conventions/layout), or [Route Handler](/docs/app/api-reference/file-conventions/route) by directly exporting the following variables: The Route Segment options allows you to configure the behavior of a [Page](/docs/app/api-reference/file-conventions/layout), [Layout](/docs/app/api-reference/file-conventions/layout), or [Route Handler](/docs/app/api-reference/file-conventions/route) by directly exporting the following variables:
......
...@@ -173,7 +173,13 @@ export default function Page() { ...@@ -173,7 +173,13 @@ export default function Page() {
} }
``` ```
> **Good to know**: In development, all pages are rendered on-demand, so `useSearchParams` doesn't suspend. However, pre-rendering a [static page](/docs/app/getting-started/partial-prerendering#static-rendering) that worked in development will fail the build if `useSearchParams` is used in a Client Component that isn’t directly or indirectly wrapped in a `Suspense` boundary. > **Good to know**:
>
> - In development, routes are rendered on-demand, so `useSearchParams` doesn't suspend and things may appear to work without `Suspense`.
> - During production builds, a [static page](/docs/app/getting-started/partial-prerendering#static-rendering) that calls `useSearchParams` from a Client Component must be wrapped in a `Suspense` boundary, otherwise the build fails with the [Missing Suspense boundary with useSearchParams](/docs/messages/missing-suspense-with-csr-bailout) error.
> - If you intend the route to be dynamically rendered, prefer using the [`connection`](/docs/app/api-reference/functions/connection) function first in a Server Component to wait for an incoming request, this excludes everything below from prerendering. See what makes a route dynamic in the [Dynamic Rendering guide](/docs/app/getting-started/partial-prerendering#dynamic-rendering).
> - If you're already in a Server Component Page, consider using the [`searchParams` prop](/docs/app/api-reference/file-conventions/page#searchparams-optional) and passing the values to Client Components.
> - You can also pass the Page [`searchParams` prop](/docs/app/api-reference/file-conventions/page#searchparams-optional) directly to a Client Component and unwrap it with React's `use()`. Although this will suspend, so the Client Component should be wrapped with a `Suspense` boundary.
### Dynamic Rendering ### Dynamic Rendering
...@@ -218,11 +224,11 @@ export default function SearchBar() { ...@@ -218,11 +224,11 @@ export default function SearchBar() {
``` ```
```tsx filename="app/dashboard/page.tsx" switcher ```tsx filename="app/dashboard/page.tsx" switcher
import { connection } from 'next/server'
import SearchBar from './search-bar' import SearchBar from './search-bar'
export const dynamic = 'force-dynamic' export default async function Page() {
await connection()
export default function Page() {
return ( return (
<> <>
<nav> <nav>
...@@ -235,11 +241,11 @@ export default function Page() { ...@@ -235,11 +241,11 @@ export default function Page() {
``` ```
```jsx filename="app/dashboard/page.js" switcher ```jsx filename="app/dashboard/page.js" switcher
import { connection } from 'next/server'
import SearchBar from './search-bar' import SearchBar from './search-bar'
export const dynamic = 'force-dynamic' export default async function Page() {
await connection()
export default function Page() {
return ( return (
<> <>
<nav> <nav>
...@@ -251,7 +257,9 @@ export default function Page() { ...@@ -251,7 +257,9 @@ export default function Page() {
} }
``` ```
> **Good to know**: Setting the [`dynamic` route segment config option](/docs/app/api-reference/file-conventions/route-segment-config#dynamic) to `force-dynamic` can be used to force dynamic rendering. > **Good to know**:
>
> - Previously, setting `export const dynamic = 'force-dynamic'` on the page was used to force dynamic rendering. Prefer using [`connection()`](/docs/app/api-reference/functions/connection) instead, as it semantically ties dynamic rendering to the incoming request.
### Server Components ### Server Components
......
...@@ -8,7 +8,110 @@ Reading search parameters through `useSearchParams()` without a Suspense boundar ...@@ -8,7 +8,110 @@ Reading search parameters through `useSearchParams()` without a Suspense boundar
## Possible Ways to Fix It ## Possible Ways to Fix It
Ensure that calls to `useSearchParams()` are wrapped in a Suspense boundary. You have a few options depending on your intent:
- To keep the route statically generated, wrap the smallest subtree that calls `useSearchParams()` in `Suspense`, for example you may move its usage into a child Client Component and render that component wrapped with `Suspense`. This preserves the static shell and avoids a full CSR bailout.
- To make the route dynamically rendered, use the [`connection`](/docs/app/api-reference/functions/connection) function in a Server Component (e.g. the Page or a wrapping Layout). This waits for an incoming request and excludes everything below from prerendering.
```tsx filename="app/page.tsx" switcher
import { connection } from 'next/server'
export default async function Page() {
await connection()
return <div>...</div>
}
```
```jsx filename="app/page.js" switcher
import { connection } from 'next/server'
export default async function Page() {
await connection()
return <div>...</div>
}
```
- Before the `connection` API was available setting `export const dynamic = 'force-dynamic'` in a Server Component `page.tsx`, or `layout.tsx`, opted the route into on-demand rendering. Note that setting `dynamic` in a Client Component (`'use client'`) `page.tsx` has no effect.
```tsx filename="app/layout.tsx" switcher
export const dynamic = 'force-dynamic'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return children
}
```
```jsx filename="app/layout.js" switcher
export const dynamic = 'force-dynamic'
export default function RootLayout({ children }) {
return children
}
```
- Alternatively, a Server Component Page can pass the `searchParams` value down to Client Components. In a Client Component, you can unwrap it with React's `use()` (ensure a surrounding `Suspense` boundary). See [What to use and when](/docs/app/getting-started/layouts-and-pages#what-to-use-and-when).
```tsx filename="app/page.tsx" switcher
import { Suspense } from 'react'
import ClientSearch from './client-search'
export default function Page({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
return (
<Suspense fallback={<>...</>}>
<ClientSearch searchParams={searchParams} />
</Suspense>
)
}
```
```tsx filename="app/client-search.tsx" switcher
'use client'
import { use } from 'react'
export default function ClientSearch({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
const params = use(searchParams)
return <div>Query: {params.q}</div>
}
```
```jsx filename="app/page.js" switcher
import { Suspense } from 'react'
import ClientSearch from './client-search'
export default function Page({ searchParams }) {
return (
<Suspense fallback={<>...</>}>
<ClientSearch searchParams={searchParams} />
</Suspense>
)
}
```
```jsx filename="app/client-search.js" switcher
'use client'
import { use } from 'react'
export default function ClientSearch({ searchParams }) {
const params = use(searchParams)
return <div>Query: {params.q}</div>
}
```
- Consider making the Page a Server Component again and isolating Client-only code (that uses `useSearchParams`) into child Client Components.
```tsx filename="app/search.tsx" switcher ```tsx filename="app/search.tsx" switcher
'use client' 'use client'
...@@ -54,8 +157,6 @@ export function Searchbar() { ...@@ -54,8 +157,6 @@ export function Searchbar() {
} }
``` ```
This will ensure the page does not de-opt to client-side rendering.
## Disabling ## Disabling
> **Note**: This is only available with Next.js version 14.x. If you're in versions above 14 please fix it with the approach above. > **Note**: This is only available with Next.js version 14.x. If you're in versions above 14 please fix it with the approach above.
...@@ -75,3 +176,5 @@ This configuration option will be removed in a future major version. ...@@ -75,3 +176,5 @@ This configuration option will be removed in a future major version.
## Useful Links ## Useful Links
- [`useSearchParams`](/docs/app/api-reference/functions/use-search-params) - [`useSearchParams`](/docs/app/api-reference/functions/use-search-params)
- [`connection`](/docs/app/api-reference/functions/connection)
- [Dynamic Rendering guide](/docs/app/getting-started/partial-prerendering#dynamic-rendering)
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