Enable Cache Components

Next.js 16 introduces Cache Components that replaces the old implicit caching model and makes data fetching dynamic by default. You have to use the 'use cache' directive to perform caching giving you more control over what is cached and their duration.

For a SitecoreAI Content SDK application, this means:

• Editing and preview modes always bypass the cache.
• Every component is handled individually and you should not wrap the <Placeholder/> component with <Suspense/>.
• Cached data is automatically refreshed after a set duration using cacheLife.
• You can manually invalidate cached data after a mutation using revalidateTag, updateTag, or revalidatePath.
• You can render content at runtime using the connection() function and not pre-render at build time. This usually occurs when you access external information that you intentionally want to change the result of a render, such as Math.random() or new Date().

To set up Cache Components in your Content SDK Pages Router app:

1. In your next.config.ts file, enable the cacheComponents flag as shown:

   const nextConfig: NextConfig = {
     cacheComponents: true,
     ...
   };

2. All route handlers are dynamic by default when using Cache Components. The route segment configuration in your route handlers is therefore incompatible and must be removed. In the following files:

   • src/app/api/editing/config/route.ts
   • src/app/api/editing/render/route.ts
   • src/app/api/sitemap/route.ts
   • src/app/api/robots/route.ts

   Remove the following line:

   export const dynamic = 'force-dynamic';

3. Copy the 3 cached versions of your data fetching functions for page, dictionary, and error page requests into the src/lib/cache folder.

4. After copying the data fetching functions, you must now update references to use them.

   • In /[[...path]]/page.ts, replace instances of the client.getPage function in the component and generateMetadata functions with the getSitecorePage function from src/lib/cache:

     // Before
     await client.getPage(path ?? [], { site, locale });
     
     // After
     import { getSitecorePage } from 'src/lib/cache/get-sitecore-page';
     
     const page = await getSitecorePage({ site, locale, path: path ?? [] });

     Important

     Do not wrap the component with 'use cache';.

     In the draft.isEnabled block, do not route client.getPreview and client.getDesignLibraryData through cache helpers.

   • In src/app/not-found.tsx and /[[...path]]/not-found.tsx, replace instances of client.getErrorPage with the getSitecoreErrorPage function from src/lib/cache:

     // Before
     await client.getErrorPage(ErrorPage.NotFound, { site, locale });
     
     // After
     import { getSitecoreErrorPage } from 'src/lib/cache/get-sitecore-error-page';
     import { ErrorPage } from '@sitecore-content-sdk/nextjs';
     
     const page = await getSitecoreErrorPage({ site, locale, code: ErrorPage.NotFound });

     Important

     Do not apply 'use cache'; to the entire NotFound component. The file relies on getCachedPageParams() inside the cached boundary, and React cache boundaries do not align with Next.js cache context in this case.

   • In global-error.tsx, verify that it renders a dedicated layout that does not reference any cache components, as global-error is a client component. You will most likely need to introduce a separate layout rather than using a shared one.

   • In i18n/request.ts, replace instances of client.getDictionary with the getSitecoreDictionary function from the src/lib/cache folder:

     // Before
     await client.getDictionary({ site, locale });
     
     // After
     import { getSitecoreDictionary } from 'src/lib/cache/get-sitecore-dictionary';
     
     const dictionary = await getSitecoreDictionary({ site, locale });

     Important

     You must disable the SDK's dictionary cache in the client configuration (sitecore.config.ts) so that it doesn't clash with the Cache Components layer:

     defineConfig({
     ...
     dictionary: { caching: { enabled: false } },
     });

import {
  collectSitecorePageCacheTags,
  buildSitecoreDictionaryCacheTag,
} from '@sitecore-content-sdk/nextjs';

collectSitecorePageCacheTags({
  site,
  locale,
  path,
  route,
});

buildSitecoreDictionaryCacheTag({
  site,
  locale,
});