dynamicParams = false for Cache Components & non-inheriting behavior

[amannn]

dynamicParams = false is a useful feature for running validation of dynamic segments before rendering of the app starts. I think this pattern is especially useful when working with top-level dynamic segments like [locale], which are common for apps that support internationalization.

However, when using the cacheComponents feature, you currently see this error:

"dynamicParams" is not compatible with `nextConfig.experimental.cacheComponents`. Please remove it.

Based on the comment from @sebmarkbage at #71927 (comment), it seems like a different alternative is planned. There was a follow-up discussion with @wyattjoh in #84738 which prompted the creation of this discussion.

A related gotcha of using dynamicParams = false is that it enforces inheriting this behavior for the route tree. For apps that use this at a top-level segment, this requires you to define generateStaticParams for all nested dynamic segments you might have—otherwise you'll run into 404s by default (e.g. /[locale]/stories/[slug] → any [slug] will by default be a 404 if ./stories/layout.tsx doesn't export generateStaticParams—see also #84738).

From my perspective, an ideal feature would:

1. Allow using central validation for allowed values of dynamic segments before rendering starts
2. Use this validation for a single segment, instead of inheriting this behavior

Potential solutions:

1. Implement support for dynamicParams = false for cacheComponents (are there any API constraints here?)
2. Change dynamicParams = false to not inherit and ask developers to provide this for all levels where it should apply (breaking change, but with automated upgrade path)
3. Add a new API like interceptor.ts that runs before rendering, but allow it to not opt the corresponding pages into dynamic rendering (ref)

Regarding the last item, it could look like this:

// app/[locale]/interceptor.ts
export default async function intercept({request, params}: InterceptorProps<'/[locale]'>): Promise<void> {
  // Only if this is called, we'll switch to dynamic rendering
  // const info = await request();

  // Static or dynamic, depending on if the value is present in `generateStaticParams`
  const {locale} = await params();
  if (!['en', 'de'].includes(locale)) {
    notFound();
  }
}

Alternatives today:

1. Use manual validation of dynamic segment values during render. In practice, this can be rather cumbersome though since pages and layouts render in parallel (esp. with nested segments rendering in parallel as well)

These are a few thoughts from my position, if the Next.js team could share more insights on this topic and potential constraints, I'd be really curious to discuss some ideas!

[apostolos]

Isn't this solved with next/root-params already? What I do is wrap the imported param function and do the validation there centrally and then use that across the app instead of importing from root-params directly:

import { locale } from 'next/root-params'
import { notFound } from 'next/navigation'

export async function getLocale(): Promise<string> {
  const resolved = await locale()
  if (!['en', 'de'].includes(resolved)) {
    notFound()
  }
  return resolved;
}

If the validation is expensive for whatever reason (maybe you have to go the database or a remote service), you can just cache it.

To me this is far more flexible than rigid exports like dynamicParams.

I'm including an explainer about root-params for people that don't know about them, because they are still undocumented:

What is next/root-params ??

With a layout like the following:

• src
  • app
    • proxy.ts
    • [tenant]
      • [locale]
        • layout.tsx
        • page.tsx
        • (...)

You can just do:

import { tenant, locale } from 'next/root-params'

These are magically created functions that you need to await:

const resolvedLocale = await locale()
const resolvedTenant = await tenant()

and they are available anywhere in the app from that path downwards (no Suspense boundary is required). Very handy.

There are two prerequisites though:

• The root layout.tsx MUST be at that level. You can still have other root layouts, root-params will export all discovered params but only resolve those that belong to the respective path.
• To avoid turning pages to dynamic, and thus requiring Suspense boundaries, you need to export generateStaticParams that returns at least one value for each root param (you don't have to return all possible values, Next.js will ISR the rest).

Example:

export async function generateStaticParams() {
  return locales.map((locale) => ({ locale, tenant: 'knownTenantId' }));
}

Warning

If you do the above, and if your routes are fully or partially static, Next.js will literally generate separate ISR cache entries for each root param combination. This might balloon disk usage (or external cache if you're using an adapter). Scaling and cost planning can be a challenge for some kinds of apps.

[thebuilder]

This works when you enable cacheComponents, but it still doesn't work if you try to add use cache to your pages.

 Route /[[...slug]] used `import('next/root-params').slug()` inside `"use cache"` or `unstable_cache`. Support for this API inside cache scopes is planned for a future version of Next.js.

[apostolos]

@thebuilder Yes, that's a limitation of the current implementation.

You need to resolve at a higher level and pass the value as a prop or function argument (depending on where you're using the "use cache"). Then it works fine.

[thebuilder]

I would like to use it for the entire page, since it's static content, but the locale is needed to fetch the right data throughout the page, either from translations or api endpoints. E.. the request.ts in next-intl needs it

[apostolos]

@thebuilder next-intl will definitely need to change in order to make use of root-params. The default setup at least.

You could try this guide https://next-intl.dev/docs/routing/setup#static-rendering but instead of reading from params, read from root-params. I'm not familiar with the library, but it might work.

[amannn]

next-intl@4 has in fact been designed to work flawlessly with next/root-params as soon as it's available.

It's a small change in i18n/request.ts:

import * as rootParams from 'next/root-params';
import {getRequestConfig} from 'next-intl/server';
import {hasLocale} from 'next-intl';
import {routing} from './routing';
 
export default getRequestConfig(async () => {
  const paramValue = await rootParams.locale();
  const locale = hasLocale(routing.locales, paramValue)
    ? paramValue
    : routing.defaultLocale;
 
  return {
    locale,
    messages: (await import(`../../messages/${locale}.json`)).default
  };
});

The currently available setRequestLocale was in fact only added as a stopgap solution until something like next/root-params is introduced that works with static rendering out of the box.

But yes, re: cacheComponents, this currently doesn't work when reading a root param inside the cache boundary. However, the API for next/root-params was changed from the previous unstable_rootParams precisely for enabling this use case. So for this combination, we'll have to wait until Next.js adds support.