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

jacekradko · 2026-01-14T02:42:08Z

Summary

Adds baseline support for Next.js 16 cache components (cacheComponents) by improving error detection and providing helpful error messages.

Add isNextjsUseCacheError() helper to detect "use cache" context errors
Update isPrerenderingBailout() to detect cache component prerendering errors
Update buildRequestLike() to provide helpful error message when auth() is called inside a "use cache" function
Update clerkClient() to re-throw "use cache" errors
Add unit tests for error detection helpers

Problem

When Next.js 16 cache components are enabled and a developer calls auth() or currentUser() inside a "use cache" function, they receive a cryptic error about headers() rejecting during prerendering.

Solution

Detect these errors and provide a helpful message with a code example showing the correct pattern:

Clerk: auth() and currentUser() cannot be called inside a "use cache" function.
These functions access `headers()` internally, which is a dynamic API not allowed in cached contexts.

To fix this, call auth() outside the cached function and pass the userId as an argument:

  async function getCachedUser(userId: string) {
    "use cache";
    const client = await clerkClient();
    return client.users.getUser(userId);
  }

  // In your component/page:
  const { userId } = await auth();
  if (userId) {
    const user = await getCachedUser(userId);
  }

Test plan

Unit tests added for isPrerenderingBailout() and isNextjsUseCacheError()
All 26 tests pass
Build succeeds
Manual testing with Next.js 16 test app (follow-up)

How to verify

Setup

Create or use a Next.js 16 app with cacheComponents enabled in next.config.ts:

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

Install the PR preview package:

npm i https://pkg.pr.new/@clerk/nextjs@7595

Test the error detection

Create a page that calls auth() inside a "use cache" function:

// app/test-cache/page.tsx
import { auth } from '@clerk/nextjs/server';

async function getCachedData() {
  "use cache";
  const { userId } = await auth(); // ❌ This should trigger our helpful error
  return { userId };
}

export default async function TestPage() {
  const data = await getCachedData();
  return <div>{JSON.stringify(data)}</div>;
}

Expected behavior

Before this PR: Cryptic error about headers() rejecting during prerendering

After this PR: Clear error message explaining the issue and showing the correct pattern:

Clerk: auth() and currentUser() cannot be called inside a "use cache" function.
These functions access `headers()` internally, which is a dynamic API not allowed in cached contexts.

To fix this, call auth() outside the cached function and pass the userId as an argument:
...

Summary by CodeRabbit

New Features
- Added support for Next.js 16 cache components with improved error detection and handling capabilities.
Improvements
- Clearer error messages when authentication functions are used incorrectly inside a "use cache" function.
- Enhanced error handling across server utilities for cache boundary detection and prerendering scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

- Add `isNextjsUseCacheError()` helper to detect "use cache" context errors - Update `isPrerenderingBailout()` to detect cache component prerendering errors - Update `buildRequestLike()` to provide helpful error message with code example when auth() is called inside a "use cache" function - Update `clerkClient()` to re-throw "use cache" errors - Add unit tests for error detection helpers

changeset-bot · 2026-01-14T02:42:13Z

🦋 Changeset detected

Latest commit: 376fd84

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-01-14T02:42:14Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Skipped		Jan 15, 2026 5:45pm

coderabbitai · 2026-01-14T02:44:23Z

📝 Walkthrough

Walkthrough

Adds detection and handling for Next.js 16 "use cache" component errors across the Clerk Next.js package. Introduces precompiled regexes, an exported helper isNextjsUseCacheError, and USE_CACHE_ERROR_MESSAGE. Integrates detection into buildRequestLike, clerkClient, auth, and currentUser to rethrow matched errors with a standardized message. Adds tests for isPrerenderingBailout and isNextjsUseCacheError, and a changeset documenting the capability.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly and accurately summarizes the main change: adding support for Next.js 16 cache components with improved error detection and clearer error messages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 16cb41b and 376fd84.

📒 Files selected for processing (1)

packages/nextjs/src/app-router/server/utils.ts

🧰 Additional context used

📓 Path-based instructions (10)

**/*.{js,jsx,ts,tsx}