Experience with next/root-params

[amannn]

With next/root-params being available in Next.js 16.3, I'd be curious to hear how this feature is working for users of next-intl!

Here's a blog post I wrote on it:
→ Using next/root-params in Next.js 16.3

My impression so far has been very positive, these are my findings:

• Server Actions are not yet supported
• Route Handlers are not yet supported
• If you're using createMiddleware from next-intl in a proxy, be sure to split calls to defineRouting and createNavigation into separate files (ref)

Let me know if next/root-params works well for your app!

(this discussion initially tracked an earlier version of next/root-params but is now updated for Next.js 16.3)

[sannajammeh]

This API does not work for me currently in 15 latest canary. It simply returns {} for every page its called in

[amannn]

Do you by chance have a layout at app/layout.tsx? If so, that would cause the empty object. You need to make sure that you only have layouts in nested folders like [locale].

[nevnein]

FYI this has been moved from unstable_rootParams to its own package(?), see https://github.com/vercel/next.js/releases/tag/v15.4.2-canary.42 and vercel/next.js#82582

[amannn]

Yep, unstable_rootParams will be replaced by next/root-params.

It's pretty much an equivalent for the previous API with one minor difference: Server Actions are (currently) not supported. AFAIK this is still under consideration and may change.

With Next.js 15.5, a deprecation notice for unstable_rootParams was added, but the API will continue to work until Next.js 16.

[GrahamQuan]

on next 15.5.0, current api can await a value, but any type

import { locale } from 'next/root-params';

const localeValue = await locale(); // `localeValue` type is any

i wonder how to add types in the future, locale() should be Promise<'en' | 'es' | ...>

[amannn]

I think it's coming: vercel/next.js#80618

[jokull]

We just shipped triptojapan.com with root params. The code cleanup is great and we are finally using generateStaticParams.

The only issue we ran into was in preview environments. In generateStaticParams we early returned an empty array, in combination with export const dynamicParams = true; to clamp down build times in preview environments. This resulted in errors for all routes with generateStaticParams, only preview envs but not in dev. Adding just a single prebuilt route with slice(0, 1) made it work.

[amannn]

Nice! 💯

This resulted in errors for all routes with generateStaticParams

That's odd! Thanks for sharing your workaround though!

[sannajammeh]

We also shipped https://nordicdownhillseries.com with root params. Works excellent!

[kachkaev]

What is the current state of this feature? I see a few related PRs from Summer 2025 (e.g. vercel/next.js#82244) but it's been pretty quiet since then. Is Next.js still considering next/root-params the right abstraction or should we wait for something else instead? Mainly curious about root params in context of "use cache" and i18n.

[aidenlx]

At least in nextjs 16 release blog, they stated that an API is currently been worked on (probably mean next/root-params?) to replace unstable_rootParams() and will be shipped in an upcoming minor.

https://nextjs.org/blog/next-16#breaking-changes-and-other-updates:~:text=unstable_rootParams()

[GrahamQuan]

it works great 🫶

git: https://github.com/GrahamQuan/nextjs-root-params-i18n

web: https://nextjs-root-params-i18n.vercel.app/

[Michaelkire]

I ran into an issue where I couldn't finish the implementation due to the following:

Your docs / blog tells to use the root param fetcher in the request config. However when I do, Nextjs yells at me, saying that it should be used in the app directory only.

Not sure if it due to us using useExtracted. I will have to dig deeper.

[amannn]

Hmm, no—useExtracted shouldn’t make a difference here. Are you using the App Router or are you in some kind of migration state? Maybe your agent can isolate a minimal reproduction that demonstrates the issue so I can have a look!

[ClementDreptin]

I ran into a similar issue today. It took me a while but I think I found the cause.

In the basic example-app-router example, there is src/i18n/routing.ts that exports the routing configuration like so:

import {defineRouting} from 'next-intl/routing';

export const routing = defineRouting({
  locales: ['en', 'de'],
  defaultLocale: 'en',
  pathnames: {
    '/': '/',
    '/pathnames': {
      de: '/pfadnamen'
    }
  }
});

and src/i18n/navigation.ts that exports the wrappers around the next/navigation hooks and components like so:

import {createNavigation} from 'next-intl/navigation';
import {routing} from './routing';

export const {Link, getPathname, redirect, usePathname, useRouter} =
  createNavigation(routing);

In our app, src/i18n/routing.ts and src/i18n/navigation.ts are merged into a single file that looks like this:

import { createNavigation } from "next-intl/navigation";
import { defineRouting } from "next-intl/routing";

export const routing = defineRouting({
  locales: ["fr-FR", "en-GB", "es-ES"],
  defaultLocale: "fr-FR",
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);`

For whatever reason, the last 2 lines create the following crash:

Error: Invalid import
'next/root-params' can only be used inside the App Directory.
The error was caused by importing 'root-params.js'

Import trace:
  Middleware:
    [next]/root-params.js
    ...

Simply calling createNavigation without even exporting its result is enough to reproduce the crash.

To reproduce the crash on your end, simply run example-app-router with the following changes:

+import {createNavigation} from 'next-intl/navigation';
import {defineRouting} from 'next-intl/routing';

export const routing = defineRouting({
  locales: ['en', 'de'],
  defaultLocale: 'en',
  pathnames: {
    '/': '/',
    '/pathnames': {
      de: '/pfadnamen'
    }
  }
});
+
+createNavigation(routing);

I would be very curious to know why this happens, because the error message didn't help at all here.

[amannn]

What exactly is the error message you're seeing?

FWIW I switched the next-intl docs to use a separate file for createNavigation and defineRouting during the switch to Next.js 15, as that already showed issues: #1669

Haven't tested having both calls in a single file in a longer time but would certainly recommend to separate them due to Next.js bundling behavior.

[ClementDreptin]

Here's the full error shown in the browser:

Error: Invalid import
'next/root-params' can only be used inside the App Directory.
The error was caused by importing 'root-params.js'

Import trace:
  Middleware:
    [next]/root-params.js
    ./src/i18n/request.ts
    ./node_modules/.pnpm/next-intl@4.13.6_@swc+helpers@0.5.23_next@16.3.1_@babel+core@7.29.0_supports-color@8.1._8b275c2cc7372963a1f783f3f9c70c09/node_modules/next-intl/dist/esm/development/server/react-server/getConfig.js
    ./node_modules/.pnpm/next-intl@4.13.6_@swc+helpers@0.5.23_next@16.3.1_@babel+core@7.29.0_supports-color@8.1._8b275c2cc7372963a1f783f3f9c70c09/node_modules/next-intl/dist/esm/development/navigation/react-server/getServerLocale.js
    ./node_modules/.pnpm/next-intl@4.13.6_@swc+helpers@0.5.23_next@16.3.1_@babel+core@7.29.0_supports-color@8.1._8b275c2cc7372963a1f783f3f9c70c09/node_modules/next-intl/dist/esm/development/navigation/react-server/createNavigation.js
    ./src/i18n/routing.ts
    ./src/proxy.ts

If having everything in the same file also causes bundle size issues, I have one more reason to keep things separate.

[amannn]

Ah yep, it seems like the bundling layer for the middleware is not considered "App Directory" for some reason.

But yeah, splitting the file is the way to go 👍