Skip to content

feat(nextjs): Add support for Next.js 16 cache components #7595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jacekradko wants to merge 11 commits into
base: main
Choose a base branch
from
Open

feat(nextjs): Add support for Next.js 16 cache components #7595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f5da1c6
feat(nextjs): Add support for Next.js 16 cache components
jacekradko Jan 14, 2026
5a1d4c3
fix(nextjs): catch use cache errors at auth/currentUser level
jacekradko Jan 14, 2026
16cb41b
refactor: hoist route bailout regex pattern to module level
jacekradko Jan 15, 2026
376fd84
style: format utils.ts
jacekradko Jan 15, 2026
3f20681
Update packages/nextjs/src/app-router/server/utils.ts
jacekradko Feb 3, 2026
e4f48fb
Merge branch 'main' into feat/nextjs-cache-components-support
jacekradko Feb 3, 2026
eed6aeb
Merge branch 'main' into feat/nextjs-cache-components-support
jacekradko Feb 4, 2026
db8d6de
test(nextjs): add E2E tests for cache components support
jacekradko Feb 4, 2026
6fa6c93
fix(nextjs): prevent double-wrapping of use cache errors
jacekradko Feb 4, 2026
1686fb2
Merge branch 'main' into feat/nextjs-cache-components-support
jacekradko Feb 4, 2026
3404ed3
chore: format
jacekradko Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/nextjs-cache-components-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clerk/nextjs': patch
---

Add support for Next.js 16 cache components by improving error detection and providing helpful error messages when `auth()` or `currentUser()` are called inside a `"use cache"` function.
19 changes: 19 additions & 0 deletions integration/templates/next-cache-components/src/app/api/use-cache-error-trigger/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
import { auth } from '@clerk/nextjs/server';

// This function deliberately calls auth() inside "use cache" to trigger the error
async function getCachedAuthData() {
'use cache';
// This WILL throw an error because auth() uses headers() internally
const { userId } = await auth();
return { userId };
}

export async function GET() {
try {
const data = await getCachedAuthData();
return Response.json(data);
} catch (e: any) {
// Return the error message so we can verify it in tests
return Response.json({ error: e.message }, { status: 500 });
}
}
93 changes: 93 additions & 0 deletions integration/templates/next-cache-components/src/app/current-user-cache-correct/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
import { Suspense } from 'react';
import { currentUser, clerkClient } from '@clerk/nextjs/server';

// Simulated cached operation that fetches additional user data
async function getCachedUserProfile(userId: string) {
'use cache';
// This is the CORRECT pattern:
// - currentUser() is called OUTSIDE the cache function
// - Only the userId is passed into the cache function
// - The cache function uses clerkClient() which is allowed in cache contexts
const client = await clerkClient();
const user = await client.users.getUser(userId);

return {
userId,
cachedAt: new Date().toISOString(),
profile: {
fullName: [user.firstName, user.lastName].filter(Boolean).join(' ') || 'Unknown',
emailCount: user.emailAddresses?.length ?? 0,
},
};
}

async function CurrentUserCacheContent() {
// Step 1: Call currentUser() OUTSIDE the cache function
const user = await currentUser();

if (!user) {
return (
<>
<p>Please sign in to test the caching pattern with currentUser().</p>
<div data-testid='signed-out'>Not signed in</div>
</>
);
}

// Step 2: Pass userId INTO the cache function
const cachedProfile = await getCachedUserProfile(user.id);

return (
<>
<p>
This demonstrates the correct way to use <code>&quot;use cache&quot;</code> with currentUser():
</p>
<ol>
<li>
Call <code>currentUser()</code> <strong>outside</strong> the cache function
</li>
<li>
Pass the <code>userId</code> <strong>into</strong> the cache function
</li>
<li>
Use <code>clerkClient()</code> inside the cache function (allowed)
</li>
</ol>

<div className='test-result success'>
<h3>Cached Profile Data:</h3>
<pre data-testid='cached-profile'>{JSON.stringify(cachedProfile, null, 2)}</pre>
</div>

<div data-testid='current-user-id'>{user.id}</div>

<pre>
{`
// Correct pattern:
const user = await currentUser(); // Outside cache
if (user) {
const profile = await getCachedProfile(user.id); // Pass userId in
}

async function getCachedProfile(userId: string) {
'use cache';
const client = await clerkClient();
return client.users.getUser(userId);
}
`}
</pre>
</>
);
}

export default function CurrentUserCacheCorrectPage() {
return (
<main>
<h1>currentUser() with &quot;use cache&quot; Correct Pattern</h1>

<Suspense fallback={<div>Loading...</div>}>
<CurrentUserCacheContent />
</Suspense>
</main>
);
}
43 changes: 43 additions & 0 deletions integration/templates/next-cache-components/src/app/current-user-server-component/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
import { Suspense } from 'react';
import { currentUser } from '@clerk/nextjs/server';

async function CurrentUserContent() {
const user = await currentUser();

return (
<>
<div className={`test-result ${user ? 'success' : ''}`}>
<h3>Current User Result:</h3>
<pre>
{JSON.stringify(
{
id: user?.id ?? null,
firstName: user?.firstName ?? null,
lastName: user?.lastName ?? null,
primaryEmailAddress: user?.primaryEmailAddress?.emailAddress ?? null,
isSignedIn: !!user,
},
null,
2,
)}
</pre>
</div>

<div data-testid='current-user-id'>{user?.id ?? 'Not signed in'}</div>
<div data-testid='current-user-email'>{user?.primaryEmailAddress?.emailAddress ?? 'No email'}</div>
</>
);
}

export default function CurrentUserServerComponentPage() {
return (
<main>
<h1>currentUser() in Server Component</h1>
<p>This page tests using currentUser() in a standard React Server Component.</p>

<Suspense fallback={<div>Loading user...</div>}>
<CurrentUserContent />
</Suspense>
</main>
);
}
13 changes: 11 additions & 2 deletions integration/templates/next-cache-components/src/app/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,17 +12,26 @@ export default function Home() {
<li>
<Link href='/auth-server-component'>auth() in Server Component</Link>
</li>
<li>
<Link href='/current-user-server-component'>currentUser() in Server Component</Link>
</li>
<li>
<Link href='/auth-server-action'>auth() in Server Action</Link>
</li>
<li>
<Link href='/api/auth-check'>auth() in API Route</Link>
</li>
<li>
<Link href='/use-cache-error'>use cache with auth() (should error)</Link>
<Link href='/use-cache-error'>use cache with auth() (documentation)</Link>
</li>
<li>
<Link href='/use-cache-error-trigger'>use cache error trigger (actual error)</Link>
</li>
<li>
<Link href='/use-cache-correct'>&quot;use cache&quot; correct pattern (auth)</Link>
</li>
<li>
<Link href='/use-cache-correct'>&quot;use cache&quot; correct pattern</Link>
<Link href='/current-user-cache-correct'>&quot;use cache&quot; correct pattern (currentUser)</Link>
</li>
<li>
<Link href='/ppr-auth'>PPR with auth()</Link>
Expand Down
54 changes: 54 additions & 0 deletions integration/templates/next-cache-components/src/app/use-cache-error-trigger/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
'use client';

import { useEffect, useState } from 'react';

export default function UseCacheErrorTriggerPage() {
const [error, setError] = useState<string | null>(null);
const [loading, setLoading] = useState(false);

const triggerError = async () => {
setLoading(true);
setError(null);
try {
const response = await fetch('/api/use-cache-error-trigger');
const data = await response.json();
if (data.error) {
setError(data.error);
}
} catch (e: any) {
setError(e.message);
} finally {
setLoading(false);
}
};

useEffect(() => {
triggerError();
}, []);

return (
<main>
<h1>&quot;use cache&quot; Error Trigger</h1>
<p>This page triggers an actual error by calling auth() inside a &quot;use cache&quot; function.</p>

{loading && <div data-testid='loading'>Loading...</div>}

{error && (
<div
className='test-result error'
data-testid='error-message'
>
<h3>Error Caught:</h3>
<pre style={{ whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>{error}</pre>
</div>
)}

<button
onClick={triggerError}
data-testid='trigger-btn'
>
Trigger Error Again
</button>
</main>
);
}
Loading