feat(next): prevent admin panel errors when cacheComponents is enabled (#16020)

AlessioGr · web-flow · commit 1ecd7dd1f20f · 2026-03-26T13:17:41.000-04:00
Fixes #8897, addresses #14460 Adds initial support for Next.js `cacheComponents` so users who enable it for their frontend don't get errors from the Payload admin panel. This PR addresses the obvious breakage but does not guarantee full compatibility - see the "Known Limitations" section below. When `cacheComponents` is enabled in `next.config`, Next.js throws "Data that blocks navigation was accessed outside of `<Suspense>`" errors because the admin layout reads cookies, headers, and does auth queries at the top level. This prevents users from enabling `cacheComponents` at all if Payload is in the same Next.js app. The fix has two parts. First, `withPayload` now detects `cacheComponents` in the Next.js config and sets a `PAYLOAD_CACHE_COMPONENTS_ENABLED` env var. Second, `RootLayout` reads that env var and conditionally wraps its content in `<Suspense fallback={null}>` above the `<html>` tag, which suppresses the errors. When `cacheComponents` is not enabled, the Suspense is not used at all and behavior is identical to before. ## Known Limitations These are all caused by Next.js's `cacheComponents` and likely cannot be fixed from our side. ### Page flash on hard refresh When `cacheComponents` is enabled, hard refresh shows a brief gray flash before the admin panel appears. Without `cacheComponents` there is no flash. There is no per-route opt-out for this behavior. Related issue: vercel/next.js#86739 ### HTTP status codes (404 returns 200) With `cacheComponents`, `notFound()` returns HTTP 200 instead of 404. This happens because the Suspense boundary above `<html>` causes Next.js to commit response headers (with status 200) before `notFound()` runs inside the suspended content. The not-found UI still renders correctly - only the HTTP status code is wrong. This is a [documented Next.js streaming limitation](https://nextjs.org/docs/app/api-reference/file-conventions/loading#status-codes). ### DOM accumulation breaks Playwright selectors When `cacheComponents` is enabled, Next.js wraps route segments in React's `<Activity>` component, keeping up to 3 previously visited pages in the DOM with `display: none !important` instead of unmounting them. This means Playwright selectors like `page.locator('#field-title')` resolve to multiple elements (the visible one and hidden copies from cached pages), causing strict mode violations. This is a [known issue](vercel/next.js#86577) affecting all Next.js apps using `cacheComponents` with Playwright. Because of this, we cannot reliably run our e2e test suite with `cacheComponents` enabled. Adapting the test suite would require rewriting a large number of selectors across hundreds of tests - most of our e2e tests use `page.locator()` with ID selectors, which would all break when Activity duplicates the DOM. Until the Next.js team provides a per-route opt-out for Activity (which they are [actively exploring](vercel/next.js#86577 (comment))), we cannot _guarantee_ full admin panel compatibility beyond the initial error suppression this PR provides.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -293,13 +293,14 @@ jobs:
   tests-e2e:
     runs-on: ubuntu-24.04
     needs: [e2e-matrix, e2e-prep]
-    name: E2E - ${{ matrix.suite }}${{ matrix.total-shards > 1 && format(' ({0}/{1})', matrix.shard, matrix.total-shards) || '' }}
+    name: E2E - ${{ matrix.suite }}${{ matrix.total-shards > 1 && format(' ({0}/{1})', matrix.shard, matrix.total-shards) || '' }}${{ matrix.cacheComponents && ' [cacheComponents]' || '' }}
     timeout-minutes: 45
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.e2e-matrix.outputs.matrix) }}
     env:
       SUITE_NAME: ${{ matrix.suite }}
+      PAYLOAD_CACHE_COMPONENTS: ${{ matrix.cacheComponents && 'true' || '' }}
     steps:
       - uses: actions/checkout@v5
 
@@ -396,7 +397,7 @@ jobs:
       - uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: test-results-${{ matrix.suite }}_${{ matrix.shard }}
+          name: test-results-${{ matrix.suite }}_${{ matrix.shard }}${{ matrix.cacheComponents && '_cc' || '' }}
           path: test/test-results/
           if-no-files-found: ignore
           retention-days: 1
diff --git a/.github/workflows/utilities/e2e-matrix.ts b/.github/workflows/utilities/e2e-matrix.ts
@@ -12,13 +12,16 @@ export interface TestConfig {
   shards: number
   /** Whether tests can run in parallel (default: false) */
   parallel?: boolean
+  /** Whether to enable cacheComponents for this test run */
+  cacheComponents?: boolean
 }
 
 interface MatrixEntry {
   suite: string
   shard: number
   'total-shards': number
   parallel: boolean
+  cacheComponents: boolean
 }
 
 interface Matrix {
@@ -28,13 +31,14 @@ interface Matrix {
 function generateMatrix(testConfigs: TestConfig[]): Matrix {
   const include: MatrixEntry[] = []
 
-  for (const { file, shards, parallel = false } of testConfigs) {
+  for (const { file, shards, parallel = false, cacheComponents = false } of testConfigs) {
     for (let shard = 1; shard <= shards; shard++) {
       include.push({
         suite: file,
         shard,
         'total-shards': shards,
         parallel,
+        cacheComponents,
       })
     }
   }
diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx
@@ -25,6 +25,14 @@ Payload requires the following software:
   sure you're using one of the supported version ranges listed above.
 </Banner>
 
+<Banner type="info">
+  **Cache Components:** While Next.js `cacheComponents` can be enabled alongside
+  Payload without causing errors in the admin panel, full compatibility is not
+  guaranteed. See this [GitHub pull
+  request](https://github.com/payloadcms/payload/pull/16020) for the latest
+  status.
+</Banner>
+
 ## Quickstart with create-payload-app
 
 To quickly scaffold a new Payload app in the fastest way possible, you can use [create-payload-app](https://npmjs.com/package/create-payload-app). To do so, run the following command:
diff --git a/next.config.mjs b/next.config.mjs
@@ -14,6 +14,7 @@ const withBundleAnalyzer = bundleAnalyzer({
 const config = withBundleAnalyzer(
   withPayload(
     {
+      cacheComponents: process.env.PAYLOAD_CACHE_COMPONENTS === 'true',
       basePath: process.env?.NEXT_BASE_PATH || undefined,
       typescript: {
         ignoreBuildErrors: true,
@@ -45,7 +46,7 @@ const config = withBundleAnalyzer(
             hostname: 'localhost',
           },
         ],
-        qualities: [5, 50, 75, 100]
+        qualities: [5, 50, 75, 100],
       },
       webpack: (webpackConfig) => {
         webpackConfig.resolve.extensionAlias = {
diff --git a/packages/next/src/layouts/Root/index.tsx b/packages/next/src/layouts/Root/index.tsx
@@ -6,7 +6,7 @@ import { ProgressBar, RootProvider } from '@payloadcms/ui'
 import { getClientConfig } from '@payloadcms/ui/utilities/getClientConfig'
 import { cookies as nextCookies } from 'next/headers.js'
 import { applyLocaleFiltering } from 'payload/shared'
-import React from 'react'
+import React, { Suspense } from 'react'
 
 import { getNavPrefs } from '../../elements/Nav/getNavPrefs.js'
 import { getRequestTheme } from '../../utilities/getRequestTheme.js'
@@ -21,21 +21,48 @@ export const metadata = {
   title: 'Next.js',
 }
 
-export const RootLayout = async ({
-  children,
-  config: configPromise,
-  htmlProps = {},
-  importMap,
-  serverFunction,
-}: {
+type RootLayoutProps = {
   readonly children: React.ReactNode
   readonly config: Promise<SanitizedConfig>
   readonly htmlProps?: React.HtmlHTMLAttributes<HTMLHtmlElement>
   readonly importMap: ImportMap
   readonly serverFunction: ServerFunctionClient
-}) => {
+}
+
+export const RootLayout = ({
+  children,
+  config: configPromise,
+  htmlProps,
+  importMap,
+  serverFunction,
+}: RootLayoutProps) => {
   checkDependencies()
 
+  const content = (
+    <RootLayoutContent
+      config={configPromise}
+      htmlProps={htmlProps}
+      importMap={importMap}
+      serverFunction={serverFunction}
+    >
+      {children}
+    </RootLayoutContent>
+  )
+
+  if (process.env.PAYLOAD_CACHE_COMPONENTS_ENABLED === 'true') {
+    return <Suspense fallback={null}>{content}</Suspense>
+  }
+
+  return content
+}
+
+const RootLayoutContent = async ({
+  children,
+  config: configPromise,
+  htmlProps = {},
+  importMap,
+  serverFunction,
+}: RootLayoutProps) => {
   const {
     cookies,
     headers,
diff --git a/packages/next/src/views/API/index.client.tsx b/packages/next/src/views/API/index.client.tsx
@@ -71,6 +71,14 @@ export const APIViewClient: React.FC = () => {
   )
   const [authenticated, setAuthenticated] = React.useState<boolean>(true)
   const [fullscreen, setFullscreen] = React.useState<boolean>(false)
+  const [origin, setOrigin] = React.useState<string>(serverURL || '')
+
+  // Set the origin to the window.location.origin in useEffect to avoid hydration errors
+  React.useEffect(() => {
+    if (!serverURL) {
+      setOrigin(window.location.origin)
+    }
+  }, [serverURL])
 
   const trashParam = typeof initialData?.deletedAt === 'string'
 
@@ -84,7 +92,7 @@ export const APIViewClient: React.FC = () => {
   const fetchURL = formatAdminURL({
     apiRoute,
     path: `${docEndpoint}?${params}`,
-    serverURL: serverURL || window.location.origin,
+    serverURL: origin,
   })
 
   React.useEffect(() => {
diff --git a/packages/next/src/withPayload/withPayload.js b/packages/next/src/withPayload/withPayload.js
@@ -34,6 +34,10 @@ export const withPayload = (nextConfig = {}, options = {}) => {
     env.NEXT_PUBLIC_ENABLE_ROUTER_CACHE_REFRESH = 'true'
   }
 
+  if (nextConfig.cacheComponents) {
+    env.PAYLOAD_CACHE_COMPONENTS_ENABLED = 'true'
+  }
+
   const consoleWarn = console.warn
 
   const sassWarningTexts = [
diff --git a/test/next.config.mjs b/test/next.config.mjs
@@ -14,6 +14,7 @@ const withBundleAnalyzer = bundleAnalyzer({
 export default withBundleAnalyzer(
   withPayload(
     {
+      cacheComponents: process.env.PAYLOAD_CACHE_COMPONENTS === 'true',
       devIndicators: {
         position: 'bottom-right',
       },
diff --git a/test/playwright.config.ts b/test/playwright.config.ts
@@ -7,6 +7,7 @@ const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
 
 dotenv.config({ path: path.resolve(dirname, 'test.env') })
+dotenv.config({ path: path.resolve(dirname, '..', '.env') })
 
 const CI = process.env.CI === 'true'
 

Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,10 @@ export const withPayload = (nextConfig = {}, options = {}) => {`
`34`	`34`	`env.NEXT_PUBLIC_ENABLE_ROUTER_CACHE_REFRESH = 'true'`
`35`	`35`	`}`
`36`	`36`
	`37`	`+ if (nextConfig.cacheComponents) {`
	`38`	`+ env.PAYLOAD_CACHE_COMPONENTS_ENABLED = 'true'`
	`39`	`+ }`
	`40`	`+`
`37`	`41`	`const consoleWarn = console.warn`
`38`	`42`
`39`	`43`	`const sassWarningTexts = [`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ const withBundleAnalyzer = bundleAnalyzer({`
`14`	`14`	`export default withBundleAnalyzer(`
`15`	`15`	`withPayload(`
`16`	`16`	`{`
	`17`	`+ cacheComponents: process.env.PAYLOAD_CACHE_COMPONENTS === 'true',`
`17`	`18`	`devIndicators: {`
`18`	`19`	`position: 'bottom-right',`
`19`	`20`	`},`