Unverified Commit 5795d659 authored by Joseph's avatar Joseph Committed by GitHub

docs: add next/root-params API reference (#93764)

Continuation of: https://github.com/vercel/next.js/pull/82244

Closes:
https://linear.app/vercel/issue/DOC-4924/nextroot-params-documentation

## TODO

- [x] adjust code snippets
- [x] wait for a couple more features to land (type safety support)
- [x] Route Handlers
- [x] Supported inside generateStaticParams for nested segments
- [x] x-ref for discoverability
- [x] enabled/available without a flag - the experimental flag has been
removed
parent b6fea5d0
...@@ -1254,4 +1254,4 @@ For more on Cache Components, see [Migrating to Cache Components](/docs/app/guid ...@@ -1254,4 +1254,4 @@ For more on Cache Components, see [Migrating to Cache Components](/docs/app/guid
### `unstable_rootParams` ### `unstable_rootParams`
The `unstable_rootParams` function has been removed. We are working on an alternative API that we will ship in an upcoming minor release. The `unstable_rootParams` function has been removed. Use [`next/root-params`](/docs/app/api-reference/functions/next-root-params) instead.
...@@ -96,6 +96,8 @@ async function Component({ userId }: { userId: string }) { ...@@ -96,6 +96,8 @@ async function Component({ userId }: { userId: string }) {
In the snippet above, `userId` is captured from the outer scope and `filter` is passed as an argument, so both become part of the `getData` function's cache key. This means different user and filter combinations will have separate cache entries. In the snippet above, `userId` is captured from the outer scope and `filter` is passed as an argument, so both become part of the `getData` function's cache key. This means different user and filter combinations will have separate cache entries.
> **Good to know:** When a cached function reads [root parameters](/docs/app/api-reference/functions/next-root-params), only the ones it actually reads become part of its cache key.
## Serialization ## Serialization
Arguments to cached functions and their return values must be serializable. Arguments to cached functions and their return values must be serializable.
......
...@@ -43,6 +43,8 @@ Dynamic Segments are passed as the `params` prop to [`layout`](/docs/app/api-ref ...@@ -43,6 +43,8 @@ Dynamic Segments are passed as the `params` prop to [`layout`](/docs/app/api-ref
| `app/blog/[slug]/page.js` | `/blog/b` | `{ slug: 'b' }` | | `app/blog/[slug]/page.js` | `/blog/b` | `{ slug: 'b' }` |
| `app/blog/[slug]/page.js` | `/blog/c` | `{ slug: 'c' }` | | `app/blog/[slug]/page.js` | `/blog/c` | `{ slug: 'c' }` |
Dynamic segments that appear before the [root layout](/docs/app/api-reference/file-conventions/layout#root-layout) are **root parameters**, which can additionally be read from any Server Component with [`next/root-params`](/docs/app/api-reference/functions/next-root-params).
### In Client Components ### In Client Components
In a Client Component **page**, dynamic segments from props can be accessed using the [`use`](https://react.dev/reference/react/use) API. In a Client Component **page**, dynamic segments from props can be accessed using the [`use`](https://react.dev/reference/react/use) API.
......
...@@ -143,7 +143,7 @@ export default function RootLayout({ children }) { ...@@ -143,7 +143,7 @@ export default function RootLayout({ children }) {
- Using [route groups](/docs/app/api-reference/file-conventions/route-groups) like `app/(shop)/layout.js` and `app/(marketing)/layout.js` - Using [route groups](/docs/app/api-reference/file-conventions/route-groups) like `app/(shop)/layout.js` and `app/(marketing)/layout.js`
- Omitting `app/layout.js` so layouts in subdirectories like `app/dashboard/layout.js` and `app/blog/layout.js` each become root layouts for their respective directories. - Omitting `app/layout.js` so layouts in subdirectories like `app/dashboard/layout.js` and `app/blog/layout.js` each become root layouts for their respective directories.
- Navigating **across multiple root layouts** will cause a **full page load** (as opposed to a client-side navigation). - Navigating **across multiple root layouts** will cause a **full page load** (as opposed to a client-side navigation).
- The root layout can be under a **dynamic segment**, for example when implementing [internationalization](/docs/app/guides/internationalization) with `app/[lang]/layout.js`. - The root layout can be under a **dynamic segment**, for example when implementing [internationalization](/docs/app/guides/internationalization) with `app/[lang]/layout.js`. Dynamic segments before the root layout are **root parameters** and can be read from any Server Component with [`next/root-params`](/docs/app/api-reference/functions/next-root-params).
## Caveats ## Caveats
......
...@@ -512,6 +512,8 @@ export default function Page({ params }) { ...@@ -512,6 +512,8 @@ export default function Page({ params }) {
Notice that the params argument can be accessed synchronously and includes only parent segment params. Notice that the params argument can be accessed synchronously and includes only parent segment params.
> **Good to know:** When a parent dynamic segment is a [root parameter](/docs/app/api-reference/functions/next-root-params), you can also read it inside a nested `generateStaticParams` by calling its getter from the `next/root-params` module.
For type completion, you can make use of the TypeScript `Awaited` helper in combination with either [`Page Props helper`](/docs/app/api-reference/file-conventions/page#page-props-helper) or [`Layout Props helper`](/docs/app/api-reference/file-conventions/layout#layout-props-helper): For type completion, you can make use of the TypeScript `Awaited` helper in combination with either [`Page Props helper`](/docs/app/api-reference/file-conventions/page#page-props-helper) or [`Layout Props helper`](/docs/app/api-reference/file-conventions/layout#layout-props-helper):
```ts filename="app/products/[category]/[product]/page.tsx" switcher ```ts filename="app/products/[category]/[product]/page.tsx" switcher
......
This diff is collapsed.
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