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)

Summary by CodeRabbit

New Features
- Added support for Next.js 16 cache components for improved compatibility.
Bug Fixes
- Better detection of auth/currentUser misuse inside "use cache" contexts.
- Clearer, actionable error messages guiding how to avoid cached-context conflicts.
Tests
- Added unit tests covering cache-related error detection and prerender bailout scenarios.
Documentation
- Added a changeset documenting the new cache-components support.

_{✏️ 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: 5a1d4c3

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 14, 2026 6:14pm

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

📝 Walkthrough

Walkthrough

Adds support for detecting Next.js 16 "use cache" component errors across the Clerk Next.js package. Introduces precompiled regex patterns, a new exported helper isNextjsUseCacheError, and USE_CACHE_ERROR_MESSAGE. Integrates detection into server utilities (including buildRequestLike), clerkClient, auth, and currentUser to rethrow detected errors with a standardized message. Adds tests for isPrerenderingBailout and isNextjsUseCacheError, and includes a new 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 title 'feat(nextjs): Add support for Next.js 16 cache components' directly and accurately describes the main feature being introduced—support for Next.js 16 cache components with improved error handling.

_{✏️ 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 f5da1c6 and 5a1d4c3.

📒 Files selected for processing (3)

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

🧰 Additional context used

📓 Path-based instructions (10)

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