feat(testing): Add nextjs cache components test app (#7728)

Author: jacekradko

.github/workflows/ci.yml

@@ -324,6 +324,9 @@ jobs:
           - test-name: "quickstart"
             test-project: "chrome"
             next-version: "16"
+          - test-name: "cache-components"
+            test-project: "chrome"
+            next-version: "16"
 
     steps:
       - name: Checkout Repo

integration/presets/longRunningApps.ts

@@ -36,6 +36,11 @@ export const createLongRunningApps = () => {
     { id: 'next.appRouter.withNeedsClientTrust', config: next.appRouter, env: envs.withNeedsClientTrust },
     { id: 'next.appRouter.withSharedUIVariant', config: next.appRouter, env: envs.withSharedUIVariant },
 
+    /**
+     * NextJS apps - cache components
+     */
+    { id: 'next.cacheComponents', config: next.cacheComponents, env: envs.withEmailCodes },
+
     /**
      * Quickstart apps
      */

integration/presets/next.ts

@@ -36,11 +36,23 @@ const appRouterAPWithClerkNextV6 = appRouterQuickstartV6
   .setName('next-app-router-ap-clerk-next-v6')
   .addDependency('@clerk/nextjs', '6');
 
+const cacheComponents = applicationConfig()
+  .setName('next-cache-components')
+  .useTemplate(templates['next-cache-components'])
+  .setEnvFormatter('public', key => `NEXT_PUBLIC_${key}`)
+  .addScript('setup', constants.E2E_NPM_FORCE ? 'pnpm install --force' : 'pnpm install')
+  .addScript('dev', 'pnpm dev')
+  .addScript('build', 'pnpm build')
+  .addScript('serve', 'pnpm start')
+  .addDependency('@clerk/nextjs', constants.E2E_CLERK_JS_VERSION || linkPackage('nextjs'))
+  .addDependency('@clerk/shared', linkPackage('shared'));
+
 export const next = {
   appRouter,
   appRouterTurbo,
   appRouterQuickstart,
   appRouterAPWithClerkNextLatest,
   appRouterAPWithClerkNextV6,
   appRouterQuickstartV6,
+  cacheComponents,
 } as const;

integration/templates/index.ts

@@ -5,6 +5,7 @@ export const templates = {
   // If /integration becomes a module in the future, use these helpers:
   // 'next-app-router': fileURLToPath(new URL('./next-app-router', import.meta.url)),
   'next-app-router': resolve(__dirname, './next-app-router'),
+  'next-cache-components': resolve(__dirname, './next-cache-components'),
   'next-app-router-quickstart': resolve(__dirname, './next-app-router-quickstart'),
   'next-app-router-quickstart-v6': resolve(__dirname, './next-app-router-quickstart-v6'),
   'react-cra': resolve(__dirname, './react-cra'),

integration/templates/next-cache-components/.gitignore

@@ -0,0 +1,23 @@
+# dependencies
+/node_modules
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

integration/templates/next-cache-components/README.md

@@ -0,0 +1,73 @@
+# Next.js Cache Components Integration Test App
+
+This app tests Clerk's integration with Next.js 16's experimental cache components feature.
+
+## Setup
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Configuration
+
+The app enables cache components in `next.config.js`:
+
+```js
+cacheComponents: true,  // Enables PPR and cache components
+```
+
+**Important**: ClerkProvider must be wrapped in `<Suspense>` for cache components to work correctly.
+
+## Test Scenarios
+
+### 1. auth() in Server Component (`/auth-server-component`)
+
+Tests basic usage of `auth()` in a React Server Component.
+
+### 2. auth() in Server Action (`/auth-server-action`)
+
+Tests using `auth()` inside a server action triggered by a client component.
+
+### 3. auth() in API Route (`/api/auth-check`)
+
+Tests using `auth()` in a Next.js API route handler.
+
+### 4. "use cache" with auth() - Error Case (`/use-cache-error`)
+
+Tests that calling `auth()` inside a `"use cache"` function produces the expected error.
+This is an **invalid pattern** because `auth()` uses dynamic APIs (cookies, headers).
+
+### 5. "use cache" Correct Pattern (`/use-cache-correct`)
+
+Demonstrates the correct way to use `"use cache"` with Clerk:
+
+1. Call `auth()` **outside** the cache function
+2. Pass the `userId` **into** the cache function
+3. The cache function only contains cacheable operations
+
+### 6. PPR with auth() (`/ppr-auth`)
+
+Tests Partial Pre-Rendering with authenticated content.
+Static content is pre-rendered while authenticated content streams in dynamically.
+
+### 7. Protected Route (`/protected`)
+
+Tests middleware-based route protection using `auth.protect()`.
+
+## Expected Behaviors
+
+| Scenario                          | Expected Result                            |
+| --------------------------------- | ------------------------------------------ |
+| auth() in RSC                     | Works normally                             |
+| auth() in Server Action           | Works normally                             |
+| auth() in API Route               | Works normally                             |
+| auth() inside "use cache"         | Should throw error                         |
+| userId passed to "use cache"      | Works correctly                            |
+| PPR + auth()                      | Dynamic portion streams after static shell |
+| Protected route (unauthenticated) | Redirects to sign-in                       |
+
+## Related PRs
+
+- PR #7119: Initial exploration of cacheComponents support
+- PR #7530: Initial exploration of PPR + auth() issues

integration/templates/next-cache-components/next.config.js

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  outputFileTracingRoot: '/',
+  cacheComponents: true,
+};
+
+module.exports = nextConfig;

integration/templates/next-cache-components/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "next-cache-components",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "next build",
+    "dev": "next dev",
+    "lint": "next lint",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@clerk/nextjs": "workspace:*",
+    "@types/node": "^18.19.33",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "next": "^16.0.0-canary.0",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  }
+}

integration/templates/next-cache-components/src/app/api/auth-check/route.ts

@@ -0,0 +1,12 @@
+import { auth } from '@clerk/nextjs/server';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const { userId, sessionId } = await auth();
+
+  return NextResponse.json({
+    userId: userId ?? null,
+    sessionId: sessionId ?? null,
+    isSignedIn: !!userId,
+  });
+}

integration/templates/next-cache-components/src/app/auth-server-action/actions.ts

@@ -0,0 +1,8 @@
+'use server';
+
+import { auth } from '@clerk/nextjs/server';
+
+export async function checkAuthAction() {
+  const { userId, sessionId } = await auth();
+  return { userId, sessionId };
+}