From c7c2f6604a32dc967bfd8c377fe87bb9860f0d80 Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Fri, 20 Dec 2024 10:32:29 +0100 Subject: [PATCH 1/6] docs: Add blog post for `rootParams` --- docs/src/pages/blog/_meta.tsx | 4 + docs/src/pages/blog/index.mdx | 6 + docs/src/pages/blog/next-intl-4-0.mdx | 6 +- docs/src/pages/blog/nextjs-root-params.mdx | 318 +++++++++++++++++++++ 4 files changed, 332 insertions(+), 2 deletions(-) create mode 100644 docs/src/pages/blog/nextjs-root-params.mdx diff --git a/docs/src/pages/blog/_meta.tsx b/docs/src/pages/blog/_meta.tsx index d2289e251..74bed960d 100644 --- a/docs/src/pages/blog/_meta.tsx +++ b/docs/src/pages/blog/_meta.tsx @@ -2,6 +2,10 @@ export default { index: { title: 'Overview' }, + 'nextjs-root-params': { + title: 'New in Next.js 15.X: rootParams', + display: 'hidden' + }, 'next-intl-4-0': { title: 'next-intl 4.0 beta', display: 'hidden' diff --git a/docs/src/pages/blog/index.mdx b/docs/src/pages/blog/index.mdx index 150c6ee85..4f3682930 100644 --- a/docs/src/pages/blog/index.mdx +++ b/docs/src/pages/blog/index.mdx @@ -4,6 +4,12 @@ import StayUpdated from '@/components/StayUpdated.mdx'; # next-intl blog
+ Dec XX, 2024 · by Jan Amann + +(this post is still a draft) + +Next.js v15.X was just released and with it comes a new feature: [`rootParams`](https://github.com/vercel/next.js/pull/72837). + +This new API fills in the [missing piece](https://github.com/vercel/next.js/discussions/58862) that allows apps that use top-level dynamic segments like `[locale]` to read segment values deeply in Server Components: + +```tsx +import {unstable_rootParams as rootParams} from 'next/server'; + +async function Component() { + // The ability to read params deeply in + // Server Components ... finally! + const {locale} = await rootParams(); +} +``` + +This addition is a game-changer for `next-intl`. + +While the library previously relied on workarounds to provide a locale to all Server Components, this API now provides native support in Next.js for this use case, allowing the library to integrate much tighter with Next.js. + +Practically, for users of `next-intl` this means: + +1. Being able to support static rendering of apps with i18n routing without `setRequestLocale` +2. Improved integration with the Next.js cache +3. Preparation for upcoming rendering modes in Next.js like [Partial Prerendering](https://nextjs.org/docs/app/api-reference/next-config-js/ppr) and [`dynamicIO`](https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/dynamicIO) (although there's more work necessary here on the Next.js side) + +But first, let's have a look at how this API works in practice. + +## Root layouts + +Previously, Next.js required a [root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout#root-layouts) to be present at `app/layout.tsx`. + +Now, you can move this to a nested folder, e.g.: + +``` +src +└── app + └── [locale] + ├── layout.tsx + ├── page.tsx + └── news + ├── layout.tsx + └── page.tsx +``` + +A root layout is defined as the layout that has no pages located above it. In our example, `src/app/[locale]/layout.tsx` is the root layout. In contrast, layouts that do have pages above them are regular layouts (e.g. `src/app/[locale]/news/layout.tsx`). + +That being said, with the addition of `rootParams`, you can now read the params of a root layout in all Server Components that are located below it: + +```tsx filename=src/components/LocaleSwitcher.tsx +import {unstable_rootParams as rootParams} from 'next/server'; + +export async function LocaleSwitcher() { + // Read the value of `[locale]` + const {locale} = await rootParams(); + + // ... +} +``` + +## Multiple root layouts + +Here's where it gets interesting: Since Next.js supports [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups), you can have multiple root layouts: + +``` +src +└── app + ├── [locale] + │ ├── layout.tsx + │ └── page.tsx + └── (unlocalized) + ├── layout.tsx + └── page.tsx +``` + +The layout at `[locale]/layout.tsx` as well as the layout at `(unlocalized)/layout.tsx` are on the same level, therefore both qualify as root layouts. Due to this, in this case the returned value of `rootParams` will depend on where the component that calls the function is being rendered from. + +If you call `rootParams` in shared code that is used by both root layouts, this allows for a pattern like this: + +```tsx filename="src/utils/getLocale.tsx" +import {unstable_rootParams as rootParams} from 'next/server'; + +export async function getLocale() { + // Try to read the locale in case we're in `[locale]/layout.tsx` + let {locale} = await rootParams(); + + // If we're in `(unlocalized)/layout.tsx`, let's use a fallback + if (!locale) { + locale = 'en'; + } + + return locale; +} +``` + +With this, we can use the `getLocale` function across our codebase to read the current locale without having to worry about where it's being called from. + +In an internationalized app, this can for example be useful to implement a country selection page at the root where you have to rely on a default locale. + +## Static rendering + +In case we know all possible values for the `[locale]` segment ahead of time, we can provide them to Next.js using the [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) function to enable static rendering: + +```tsx filename="src/app/[locale]/layout.tsx" +const locales = ['en', 'de']; + +// Pre-render all available locales at build time +export async function generateStaticParams() { + return locales.map((locale) => ({locale})); +} + +// ... +``` + +In combination with [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams), we can furthermore instruct Next.js to disallow values that are encountered at runtime and do not match the values we provided to `generateStaticParams`: + +```tsx filename="src/app/[locale]/layout.tsx" +// Return a 404 for any unknown locales +export const dynamicParams = false; + +// ... +``` + +## Leveraging `rootParams` in `next-intl` + +So, how can you use this feature in `next-intl`? + +Similarly to how we've defined the `getLocale` function above, we do in fact already have a shared place that is called by all server-side functions that require the current locale of the user: [`src/i18n/request.ts`](/docs/usage/configuration#server-client-components). + +Check it out: + +```tsx filename="src/i18n/request.ts" +import {unstable_rootParams as rootParams} from 'next/server'; +import {hasLocale} from 'next-intl'; +import {getRequestConfig} from 'next-intl/server'; +import {routing} from './routing'; + +export default getRequestConfig(async () => { + const params = await rootParams(); + const locale = hasLocale(routing.locales, params.locale) + ? params.locale + : routing.defaultLocale; + + return { + locale, + messages: (await import(`../../messages/${locale}.json`)).default + }; +}); +``` + +`hasLocale` is a new addition scheduled for [`next-intl@4.0`](/blog/next-intl-4-0), but practically simply checks if the provided `locales` array contains a given `locale`. If it doesn't, typically because we're not in the `[locale]` segment, a default locale is used instead. + +That's it—a single change to `src/i18n/request.ts` is all you need to do to start using `rootParams`! + +## Cleaning up + +With this change, you can now simplify your codebase in various ways: + +### Removing a pass-through root layout + +For certain patterns like global 404 pages, you might have used a pass-through root layout so far: + +```tsx filename="src/app/layout.tsx" +type Props = { + children: React.ReactNode; +}; + +export default function RootLayout({children}: Props) { + return children; +} +``` + +This needs to be removed now as otherwise this will qualify as a root layout instead of the one defined at `src/app/[locale]/layout.tsx`. + +### Avoid reading the `[locale]` segment + +Since `next-intl` provides the current locale via [`useLocale` and `getLocale`](/docs/usage/configuration#locale), you can seamlessly read the locale from these APIs instead of `params`: + +```diff filename="src/app/[locale]/layout.tsx" ++ import {getLocale} from 'next-intl/server'; + +type Props = { + children: React.ReactNode; +- params: {locale: string}; +}; + +export default async function RootLayout({ + children, +- params +}: Props) { +- const {locale} = await params; ++ const locale = await getLocale(); + + return ( + + {children} + + ); +} +``` + +Behind the scenes, if you call `useLocale` or `getLocale` in a Server Component, your `i18n/request.ts` config will be consulted, potentially using a fallback that you've defined. + +### Remove manual locale overrides [#locale-override] + +If you're using async APIs like `getTranslations`, you might have previously passed the locale manually, e.g. to enable static rendering in the Metadata API. + +Now, you can remove this and rely on the locale that is returned from `i18n/request.ts`: + +```diff filename="src/app/[locale]/page.tsx" +- type Props = { +- params: Promise<{locale: string}>; +- }; + +export async function generateMetadata( +- {params}: Props +) { +- const {locale} = await params; +- const t = await getTranslations({locale, namespace: 'HomePage'}); ++ const t = await getTranslations('HomePage'); + + // ... +} +``` + +The only case where you might still want to pass a locale to `getTranslations` is if your UI renders multiple locales in parallel. If this is the case in your app, you should make sure to accept an override in your `i18n/request.ts` config: + +```tsx filename="src/i18n/request.ts" +import {hasLocale} from 'next-intl'; +import {routing} from './routing'; + +export default getRequestConfig(async ({locale}) => { + // Use a locale based on these priorities: + // 1. An override passed to the function + // 2. A locale from the `[locale]` segment + // 3. A default locale + if (!locale) { + const params = await rootParams(); + locale = hasLocale(routing.locales, params.locale) + ? params.locale + : routing.defaultLocale; + } + + // ... +}); +``` + +### Static rendering + +If you've previously used `setRequestLocale` to enable static rendering, you can now remove it: + +```diff filename="src/[locale]/page.tsx" +- import {setRequestLocale} from 'next-intl/server'; + +- type Props = { +- params: Promise<{locale: string}>; +- } + +- export default function Page({params}: Props) { +- setRequestLocale(params.locale); ++ export default function Page() { +// ... +``` + +Note that `generateStaticParams` is naturally still required though. + +### Handling unknown locales + +Not strictly a new feature of Next.js, but in case you're using `generateStaticParams`, the easiest way to ensure that only the locales you've defined are allowed is to configure [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) in your root layout: + +```tsx filename="src/app/[locale]/layout.tsx" +// Return a 404 for any unknown locales +export const dynamicParams = false; +``` + +If you don't use `generateStaticParams`, you can still disallow unknown locales by manually calling `notFound()` in your root layout: + +```tsx filename="src/app/[locale]/layout.tsx" +import {hasLocale} from 'next-intl'; +import {notFound} from 'next/navigation'; +import {routing} from '@/i18n/routing'; + +type Props = { + children: React.ReactNode; + params: Promise<{locale: string}>; +}; + +export default async function RootLayout({children, params}: Props) { + const {locale} = await params; + if (!hasLocale(routing.locales, locale)) { + return notFound(); + } + + // ... +} +``` + +## Try `rootParams` today! + +While this article mentions an upcoming `hasLocale` API from `next-intl@4.0` that simplifies working with `rootParams`, you can already try out the API today in the `3.0` range. + +The one rare case where a change from `next-intl@4.0` is required, is if you need to [manually pass a locale](#locale-override) to async APIs like `getTranslations` in case your UI renders multiple locales in parallel. + +In case you're trying out `rootParams` with `next-intl`, let me know how it goes by joining the discussion here: [Experiences with `rootParams`](https://github.com/amannn/next-intl/discussions/1627). I'm curious to hear how it simplifies your codebase! + +—Jan + + From 0005b917867e314aaa74d3229d4d86d680fccfc7 Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Fri, 20 Dec 2024 11:36:41 +0100 Subject: [PATCH 2/6] cleanup --- docs/src/pages/blog/nextjs-root-params.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/src/pages/blog/nextjs-root-params.mdx b/docs/src/pages/blog/nextjs-root-params.mdx index a5fe55fc6..807bab472 100644 --- a/docs/src/pages/blog/nextjs-root-params.mdx +++ b/docs/src/pages/blog/nextjs-root-params.mdx @@ -141,8 +141,8 @@ Check it out: ```tsx filename="src/i18n/request.ts" import {unstable_rootParams as rootParams} from 'next/server'; -import {hasLocale} from 'next-intl'; import {getRequestConfig} from 'next-intl/server'; +import {hasLocale} from 'next-intl'; import {routing} from './routing'; export default getRequestConfig(async () => { @@ -236,6 +236,8 @@ export async function generateMetadata( The only case where you might still want to pass a locale to `getTranslations` is if your UI renders multiple locales in parallel. If this is the case in your app, you should make sure to accept an override in your `i18n/request.ts` config: ```tsx filename="src/i18n/request.ts" +import {unstable_rootParams as rootParams} from 'next/server'; +import {getRequestConfig} from 'next-intl/server'; import {hasLocale} from 'next-intl'; import {routing} from './routing'; @@ -255,6 +257,8 @@ export default getRequestConfig(async ({locale}) => { }); ``` +This is a very rare case, so if you're unsure, you very likely don't need this. + ### Static rendering If you've previously used `setRequestLocale` to enable static rendering, you can now remove it: From b54034a01393232b931db498a7367fa2578dbb6f Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Fri, 20 Dec 2024 15:29:21 +0100 Subject: [PATCH 3/6] wording --- docs/src/pages/blog/nextjs-root-params.mdx | 36 ++++++++++++++-------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/src/pages/blog/nextjs-root-params.mdx b/docs/src/pages/blog/nextjs-root-params.mdx index 807bab472..b8ed04ee9 100644 --- a/docs/src/pages/blog/nextjs-root-params.mdx +++ b/docs/src/pages/blog/nextjs-root-params.mdx @@ -26,12 +26,12 @@ async function Component() { This addition is a game-changer for `next-intl`. -While the library previously relied on workarounds to provide a locale to all Server Components, this API now provides native support in Next.js for this use case, allowing the library to integrate much tighter with Next.js. +While the library previously relied on workarounds to provide a locale to Server Components, this API now provides native support in Next.js for this use case, allowing the library to integrate much tighter with Next.js. Practically, for users of `next-intl` this means: 1. Being able to support static rendering of apps with i18n routing without `setRequestLocale` -2. Improved integration with the Next.js cache +2. Improved integration with Next.js cache mechanisms 3. Preparation for upcoming rendering modes in Next.js like [Partial Prerendering](https://nextjs.org/docs/app/api-reference/next-config-js/ppr) and [`dynamicIO`](https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/dynamicIO) (although there's more work necessary here on the Next.js side) But first, let's have a look at how this API works in practice. @@ -40,22 +40,32 @@ But first, let's have a look at how this API works in practice. Previously, Next.js required a [root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout#root-layouts) to be present at `app/layout.tsx`. -Now, you can move this to a nested folder, e.g.: +Now, you can move these to a nested folder that can be a dynamic segment, e.g.: + +``` +src +└── app + └── [locale] + ├── layout.tsx (root layout) + └── page.tsx +``` + +A root layout is a layout that has no other layouts located above it. + +In contrast, layouts that do have other layout ancestors are regular layouts: ``` src └── app └── [locale] ├── layout.tsx - ├── page.tsx + ├── (...) └── news - ├── layout.tsx + ├── layout.tsx (regular layout) └── page.tsx ``` -A root layout is defined as the layout that has no pages located above it. In our example, `src/app/[locale]/layout.tsx` is the root layout. In contrast, layouts that do have pages above them are regular layouts (e.g. `src/app/[locale]/news/layout.tsx`). - -That being said, with the addition of `rootParams`, you can now read the params of a root layout in all Server Components that are located below it: +With the addition of `rootParams`, you can now read the param values of a root layout in all Server Components that render within it: ```tsx filename=src/components/LocaleSwitcher.tsx import {unstable_rootParams as rootParams} from 'next/server'; @@ -70,7 +80,7 @@ export async function LocaleSwitcher() { ## Multiple root layouts -Here's where it gets interesting: Since Next.js supports [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups), you can have multiple root layouts: +Here's where it gets interesting: With [route groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups), you can provide another layout for pages that are not located in the `[locale]` segment: ``` src @@ -83,7 +93,7 @@ src └── page.tsx ``` -The layout at `[locale]/layout.tsx` as well as the layout at `(unlocalized)/layout.tsx` are on the same level, therefore both qualify as root layouts. Due to this, in this case the returned value of `rootParams` will depend on where the component that calls the function is being rendered from. +The layout at `[locale]/layout.tsx` as well as the layout at `(unlocalized)/layout.tsx` both have no other layouts located above them, therefore both qualify as root layouts. Due to this, in this case the returned value of `rootParams` will depend on where the component that calls the function is being rendered from. If you call `rootParams` in shared code that is used by both root layouts, this allows for a pattern like this: @@ -135,9 +145,9 @@ export const dynamicParams = false; So, how can you use this feature in `next-intl`? -Similarly to how we've defined the `getLocale` function above, we do in fact already have a shared place that is called by all server-side functions that require the current locale of the user: [`src/i18n/request.ts`](/docs/usage/configuration#server-client-components). +Similarly to how we've defined the `getLocale` function above, we do in fact already have a shared place that is called by all server-side functions that require the current locale of the user: [`i18n/request.ts`](/docs/usage/configuration#server-client-components). -Check it out: +So let's use `rootParams` here: ```tsx filename="src/i18n/request.ts" import {unstable_rootParams as rootParams} from 'next/server'; @@ -160,7 +170,7 @@ export default getRequestConfig(async () => { `hasLocale` is a new addition scheduled for [`next-intl@4.0`](/blog/next-intl-4-0), but practically simply checks if the provided `locales` array contains a given `locale`. If it doesn't, typically because we're not in the `[locale]` segment, a default locale is used instead. -That's it—a single change to `src/i18n/request.ts` is all you need to do to start using `rootParams`! +That's it—a single change to `i18n/request.ts` is all you need to do to start using `rootParams`! ## Cleaning up From 28b2c7f187abc9d9581a2eedc64a10a6cba97e6a Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Fri, 20 Dec 2024 15:44:23 +0100 Subject: [PATCH 4/6] wording --- docs/src/pages/blog/nextjs-root-params.mdx | 25 ++++++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/src/pages/blog/nextjs-root-params.mdx b/docs/src/pages/blog/nextjs-root-params.mdx index b8ed04ee9..a9b0afd78 100644 --- a/docs/src/pages/blog/nextjs-root-params.mdx +++ b/docs/src/pages/blog/nextjs-root-params.mdx @@ -194,7 +194,7 @@ This needs to be removed now as otherwise this will qualify as a root layout ins ### Avoid reading the `[locale]` segment -Since `next-intl` provides the current locale via [`useLocale` and `getLocale`](/docs/usage/configuration#locale), you can seamlessly read the locale from these APIs instead of `params`: +Since `next-intl` provides the current locale via [`useLocale` and `getLocale`](/docs/usage/configuration#locale), you can seamlessly read the locale from these APIs instead of `params` now: ```diff filename="src/app/[locale]/layout.tsx" + import {getLocale} from 'next-intl/server'; @@ -223,7 +223,7 @@ Behind the scenes, if you call `useLocale` or `getLocale` in a Server Component, ### Remove manual locale overrides [#locale-override] -If you're using async APIs like `getTranslations`, you might have previously passed the locale manually, e.g. to enable static rendering in the Metadata API. +If you're using async APIs like `getTranslations`, you might have previously passed the locale manually, typically to enable static rendering in the Metadata API. Now, you can remove this and rely on the locale that is returned from `i18n/request.ts`: @@ -243,7 +243,17 @@ export async function generateMetadata( } ``` -The only case where you might still want to pass a locale to `getTranslations` is if your UI renders multiple locales in parallel. If this is the case in your app, you should make sure to accept an override in your `i18n/request.ts` config: +The only rare case where you might still want to pass a locale to `getTranslations` is if your UI renders messages from multiple locales in parallel: + +```tsx +// Use messages from the current locale +const t = getTranslations(); + +// Use messages from 'en', regardless of what the current user locale is +const t = getTranslations({locale: 'en'}); +``` + +In this case, you should make sure to accept an override in your `i18n/request.ts` config: ```tsx filename="src/i18n/request.ts" import {unstable_rootParams as rootParams} from 'next/server'; @@ -281,9 +291,10 @@ If you've previously used `setRequestLocale` to enable static rendering, you can - } - export default function Page({params}: Props) { -- setRequestLocale(params.locale); +- setRequestLocale(params.locale); + export default function Page() { -// ... + // ... +} ``` Note that `generateStaticParams` is naturally still required though. @@ -297,7 +308,7 @@ Not strictly a new feature of Next.js, but in case you're using `generateStaticP export const dynamicParams = false; ``` -If you don't use `generateStaticParams`, you can still disallow unknown locales by manually calling `notFound()` in your root layout: +If you don't use `generateStaticParams`, you can still disallow unknown locales by manually calling `notFound()` based on `params` in your root layout: ```tsx filename="src/app/[locale]/layout.tsx" import {hasLocale} from 'next-intl'; @@ -321,7 +332,7 @@ export default async function RootLayout({children, params}: Props) { ## Try `rootParams` today! -While this article mentions an upcoming `hasLocale` API from `next-intl@4.0` that simplifies working with `rootParams`, you can already try out the API today in the `3.0` range. +While this article mentions an upcoming `hasLocale` API from `next-intl@4.0` that simplifies working with `rootParams`, you can already try out the API today even in the `3.0` range. The one rare case where a change from `next-intl@4.0` is required, is if you need to [manually pass a locale](#locale-override) to async APIs like `getTranslations` in case your UI renders multiple locales in parallel. From 0c3e628486637fcc29b652813249b34a15cf0e7a Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Fri, 20 Dec 2024 16:42:28 +0100 Subject: [PATCH 5/6] wording --- docs/src/pages/blog/nextjs-root-params.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/pages/blog/nextjs-root-params.mdx b/docs/src/pages/blog/nextjs-root-params.mdx index a9b0afd78..d826b625d 100644 --- a/docs/src/pages/blog/nextjs-root-params.mdx +++ b/docs/src/pages/blog/nextjs-root-params.mdx @@ -32,7 +32,7 @@ Practically, for users of `next-intl` this means: 1. Being able to support static rendering of apps with i18n routing without `setRequestLocale` 2. Improved integration with Next.js cache mechanisms -3. Preparation for upcoming rendering modes in Next.js like [Partial Prerendering](https://nextjs.org/docs/app/api-reference/next-config-js/ppr) and [`dynamicIO`](https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/dynamicIO) (although there's more work necessary here on the Next.js side) +3. Preparation for upcoming rendering modes in Next.js like [Partial Prerendering](https://nextjs.org/docs/app/api-reference/next-config-js/ppr) and [`dynamicIO`](https://nextjs.org/docs/canary/app/api-reference/config/next-config-js/dynamicIO) (although there seems to be more work necessary here on the Next.js side) But first, let's have a look at how this API works in practice. @@ -113,7 +113,7 @@ export async function getLocale() { } ``` -With this, we can use the `getLocale` function across our codebase to read the current locale without having to worry about where it's being called from. +With this, you can use the `getLocale` function across your codebase to read the current locale without having to worry about where it's being called from. In an internationalized app, this can for example be useful to implement a country selection page at the root where you have to rely on a default locale. @@ -172,7 +172,7 @@ export default getRequestConfig(async () => { That's it—a single change to `i18n/request.ts` is all you need to do to start using `rootParams`! -## Cleaning up +## So much cleaner With this change, you can now simplify your codebase in various ways: From 32bdd8af6179d1a49cfdc1fea7c3e2bbb40e7c5a Mon Sep 17 00:00:00 2001 From: Jan Amann Date: Wed, 15 Jan 2025 11:53:26 +0100 Subject: [PATCH 6/6] Apply suggestions from code review --- docs/src/pages/blog/nextjs-root-params.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/src/pages/blog/nextjs-root-params.mdx b/docs/src/pages/blog/nextjs-root-params.mdx index d826b625d..7767ac079 100644 --- a/docs/src/pages/blog/nextjs-root-params.mdx +++ b/docs/src/pages/blog/nextjs-root-params.mdx @@ -10,7 +10,7 @@ import StayUpdated from '@/components/StayUpdated.mdx'; (this post is still a draft) -Next.js v15.X was just released and with it comes a new feature: [`rootParams`](https://github.com/vercel/next.js/pull/72837). +Next.js v15.X was just released and comes with a new feature: [`rootParams`](https://github.com/vercel/next.js/pull/72837). This new API fills in the [missing piece](https://github.com/vercel/next.js/discussions/58862) that allows apps that use top-level dynamic segments like `[locale]` to read segment values deeply in Server Components: @@ -40,7 +40,7 @@ But first, let's have a look at how this API works in practice. Previously, Next.js required a [root layout](https://nextjs.org/docs/app/api-reference/file-conventions/layout#root-layouts) to be present at `app/layout.tsx`. -Now, you can move these to a nested folder that can be a dynamic segment, e.g.: +Now, you can move a root layout to a nested folder that can be a dynamic segment, e.g.: ``` src @@ -58,14 +58,14 @@ In contrast, layouts that do have other layout ancestors are regular layouts: src └── app └── [locale] - ├── layout.tsx + ├── layout.tsx (root layout) ├── (...) └── news ├── layout.tsx (regular layout) └── page.tsx ``` -With the addition of `rootParams`, you can now read the param values of a root layout in all Server Components that render within it: +With the addition of `rootParams`, you can now read param values of a root layout in all Server Components that render within it: ```tsx filename=src/components/LocaleSwitcher.tsx import {unstable_rootParams as rootParams} from 'next/server'; @@ -100,7 +100,7 @@ If you call `rootParams` in shared code that is used by both root layouts, this ```tsx filename="src/utils/getLocale.tsx" import {unstable_rootParams as rootParams} from 'next/server'; -export async function getLocale() { +export default async function getLocale() { // Try to read the locale in case we're in `[locale]/layout.tsx` let {locale} = await rootParams(); @@ -115,7 +115,7 @@ export async function getLocale() { With this, you can use the `getLocale` function across your codebase to read the current locale without having to worry about where it's being called from. -In an internationalized app, this can for example be useful to implement a country selection page at the root where you have to rely on a default locale. +In an internationalized app, this can for example be useful to implement a country selection page at the root where you have to rely on a default locale. Once the user is within the `[locale]` segment, this param value can be used instead for localizing page content. ## Static rendering @@ -132,7 +132,7 @@ export async function generateStaticParams() { // ... ``` -In combination with [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams), we can furthermore instruct Next.js to disallow values that are encountered at runtime and do not match the values we provided to `generateStaticParams`: +In combination with [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams), we can furthermore instruct Next.js to disallow values that are encountered at runtime and do not match the values we've provided to `generateStaticParams`: ```tsx filename="src/app/[locale]/layout.tsx" // Return a 404 for any unknown locales @@ -172,7 +172,7 @@ export default getRequestConfig(async () => { That's it—a single change to `i18n/request.ts` is all you need to do to start using `rootParams`! -## So much cleaner +## Time for spring cleaning With this change, you can now simplify your codebase in various ways: @@ -219,7 +219,7 @@ export default async function RootLayout({ } ``` -Behind the scenes, if you call `useLocale` or `getLocale` in a Server Component, your `i18n/request.ts` config will be consulted, potentially using a fallback that you've defined. +Behind the scenes, if you call `useLocale` or `getLocale` in a Server Component, your `i18n/request.ts` config will be consulted, potentially using a fallback that you have defined. ### Remove manual locale overrides [#locale-override] @@ -336,7 +336,7 @@ While this article mentions an upcoming `hasLocale` API from `next-intl@4.0` tha The one rare case where a change from `next-intl@4.0` is required, is if you need to [manually pass a locale](#locale-override) to async APIs like `getTranslations` in case your UI renders multiple locales in parallel. -In case you're trying out `rootParams` with `next-intl`, let me know how it goes by joining the discussion here: [Experiences with `rootParams`](https://github.com/amannn/next-intl/discussions/1627). I'm curious to hear how it simplifies your codebase! +If you're giving `rootParams` a go with `next-intl`, let me know how it works for you by joining the discussion here: [Experiences with `rootParams`](https://github.com/amannn/next-intl/discussions/1627). I'm curious to hear how it simplifies your codebase! —Jan