docs: next-root-params

icyJoseph · icyJoseph · commit b168933f7f9c · 2025-07-31T15:16:08.000+02:00
diff --git a/docs/01-app/03-api-reference/04-functions/next-root-params.mdx b/docs/01-app/03-api-reference/04-functions/next-root-params.mdx
@@ -0,0 +1,208 @@
+---
+title: next/root-params
+description: API Reference for the next/root-params module that provides access to root-level route parameters.
+version: canary
+---
+
+The `next/root-params` module provides individual getter functions for accessing root-level route parameters in **Server Components**. This experimental feature enables type-safe access to parameters defined in root layout segments.
+
+## Configuration
+
+To use `next/root-params`, you must enable the experimental flag in your `next.config.js`:
+
+```js filename="next.config.js"
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    rootParams: true,
+  },
+}
+
+module.exports = nextConfig
+```
+
+## Usage
+
+The module automatically generates individual getter functions for each root parameter found in your app directory structure. Root parameters are dynamic segments that appear in the path leading up to the first `layout.tsx` file.
+
+```tsx filename="app/[lang]/[locale]/page.tsx"
+import { lang, locale } from 'next/root-params'
+
+export default async function Page() {
+  return (
+    <div>
+      <h1>Language: {await lang()}</h1>
+      <p>Locale: {await locale()}</p>
+    </div>
+  )
+}
+```
+
+```tsx filename="app/[lang]/[locale]/layout.tsx"
+import { lang, locale } from 'next/root-params'
+
+export default async function Layout({ children }) {
+  return (
+    <html lang={`${await lang()}-${await locale()}`}>
+      <body>{children}</body>
+    </html>
+  )
+}
+
+export async function generateStaticParams() {
+  return [
+    { lang: 'en', locale: 'us' },
+    { lang: 'fr', locale: 'ca' },
+  ]
+}
+```
+
+## Root Parameters vs Dynamic Parameters
+
+Root parameters are different from regular dynamic parameters. They are only the parameters that exist in the path segments up to the first layout file:
+
+File structure:
+
+- `app/[lang]/[locale]/layout.tsx` - Root layout
+- `app/[lang]/[locale]/posts/[slug]/page.tsx`
+
+```tsx
+import { lang, locale } from 'next/root-params' // Available
+// import { slug } from 'next/root-params'      // Not available - 'slug' is not a root param
+
+export default async function PostPage({
+  params,
+}: {
+  params: { slug: string }
+}) {
+  const { slug } = await params // Access non-root params this way
+
+  return (
+    <div>
+      <h1>Language: {await lang()}</h1>
+      <h2>Locale: {await locale()}</h2>
+      <h3>Post: {slug}</h3>
+    </div>
+  )
+}
+```
+
+## Multiple Root Layouts
+
+Applications can have multiple root layouts with different parameter structures:
+
+File structure:
+
+- `app/dashboard/[id]/layout.tsx` - Root layout with 'id' param
+- `app/marketing/layout.tsx` - Root layout with no params
+
+```tsx
+// In dashboard pages:
+import { id } from 'next/root-params'
+
+export default async function DashboardPage() {
+  const dashboardId = await id() // Type: string | undefined
+  return <div>Dashboard ID: {dashboardId}</div>
+}
+
+// In marketing pages:
+import { id } from 'next/root-params'
+
+export default async function MarketingPage() {
+  const dashboardId = await id() // Type: string | undefined, returns undefined
+  return <div>Marketing Page</div>
+}
+```
+
+When you have multiple root layouts with different parameters, the getter functions are typed to account for all possible routes. Since `id` doesn't exist in the marketing layout, `await id()` has the type `string | undefined` to reflect that it may return `undefined` when accessed from routes without that parameter.
+
+## Catch-all and Optional Catch-all Routes
+
+Root parameters work with catch-all and optional catch-all routes:
+
+```tsx filename="app/docs/[...path]/layout.tsx"
+import { path } from 'next/root-params'
+
+export default async function DocsLayout({ children }) {
+  const pathSegments = await path() // string[] | undefined
+  return (
+    <div>
+      <nav>Path: {pathSegments?.join(' / ')}</nav>
+      {children}
+    </div>
+  )
+}
+```
+
+```tsx filename="app/optional/[[...segments]]/page.tsx"
+import { segments } from 'next/root-params'
+
+export default async function OptionalPage() {
+  const pathSegments = await segments() // string[] | undefined
+  return (
+    <div>
+      {pathSegments ? (
+        <p>Segments: {pathSegments.join(', ')}</p>
+      ) : (
+        <p>No segments</p>
+      )}
+    </div>
+  )
+}
+```
+
+## Return Values
+
+Each root parameter getter returns a `Promise` that resolves to:
+
+- `string` for regular dynamic segments like `[id]`
+- `string[]` for catch-all segments like `[...path]`
+- `string[] | undefined` for optional catch-all segments like `[[...path]]`
+- `undefined` if the parameter doesn't exist in the current route's root layout
+
+## Restrictions
+
+### Server Components Only
+
+Root parameter getters can only be used in **Server Components**:
+
+```tsx
+// This will cause a build error
+'use client'
+
+import { lang } from 'next/root-params' // Error: Cannot import in Client Component
+
+export default function ClientComponent() {
+  // ...
+}
+```
+
+### Not Available in Server Actions
+
+```tsx
+import { lang } from 'next/root-params'
+
+// This will cause a runtime error
+async function serverAction() {
+  'use server'
+  const language = await lang() // Error: Not supported in Server Actions
+}
+```
+
+### Not Available in Route Handlers
+
+```tsx filename="app/[lang]/api/route.ts"
+import { lang } from 'next/root-params'
+
+// This will cause a runtime error (support planned for future)
+export async function GET() {
+  const language = await lang() // Error: Not supported in Route Handlers yet
+  return Response.json({ lang: language })
+}
+```
+
+## Version History
+
+| Version   | Changes                                                |
+| --------- | ------------------------------------------------------ |
+| `v15.1.0` | `next/root-params` introduced as experimental feature. |
