fix(nextjs): Improve support for cacheComponents #7119

panteliselef · 2025-10-31T20:31:51Z

This PR also prevents keylessDriftDetection from firing as an action when the RSC variant is used.

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- Added configuration option to disable keyless drift detection in Clerk Provider
Improvements
- Enhanced support for Next.js cacheComponents feature
- Improved performance with optimized suspense handling and lazy loading of drift detection

This PR also prevents keylessDriftDetection from firing as an action when the RSC variant is used.

changeset-bot · 2025-10-31T20:31:55Z

🦋 Changeset detected

Latest commit: f6c4a1c

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 · 2025-10-31T20:31:57Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Oct 31, 2025 8:32pm

coderabbitai · 2025-10-31T20:32:03Z

Walkthrough

This pull request introduces drift detection for keyless authentication and adds Next.js cacheComponents support through conditional Suspense wrapping. Two new components (KeylessDriftDetector and SuspenseWhenCached) are added, the ClerkProvider is extended with drift detection controls, and telemetry flag handling is refactored to track per-public-key state.

Changes

Cohort / File(s)	Summary
Changeset `.changeset/quiet-rockets-invite.md`	Adds changeset documenting patch release with improved cacheComponents support for @clerk/nextjs.
Client-side Keyless Drift Detection `packages/nextjs/src/app-router/client/ClerkProvider.tsx`, `packages/nextjs/src/app-router/client/keyless-drift-detector.tsx`	Introduces lazy-loaded `KeylessDriftDetector` component and new `disableKeylessDriftDetection` prop to `ClientClerkProvider`. Drift detection reads layout segments and conditionally triggers `detectKeylessEnvDriftAction` when keyless is enabled.
Server-side Provider Orchestration `packages/nextjs/src/app-router/server/ClerkProvider.tsx`, `packages/nextjs/src/app-router/server/keyless-provider.tsx`	Adds server-side drift detection via `onlyTry`, wraps providers in `SuspenseWhenCached` to support cacheComponents, extends `getKeylessStatus` to return `runningWithDriftedKeys` state, and propagates `disableKeylessDriftDetection` flag.
Suspense Utility `packages/nextjs/src/app-router/suspense-when-cached.tsx`	New utility component that conditionally wraps children in React Suspense based on Next.js cache flag, with optional `noopWhen` prop to disable wrapping.
Telemetry Refactoring `packages/nextjs/src/server/keyless-telemetry.ts`	Refactors telemetry flag mechanism to track per-public-key state using template-based file paths, removes client-side guard from drift detection logic, and simplifies flag file content.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant NextApp as Next.js App
    participant ClerkServerProvider as Server ClerkProvider
    participant KeylessProvider as KeylessProvider
    participant SuspenseWhenCached as SuspenseWhenCached
    participant ClientClerkProvider as Client ClerkProvider
    participant KeylessDriftDetector as KeylessDriftDetector
    participant DriftDetection as Drift Detection Logic

    User->>NextApp: Request
    NextApp->>ClerkServerProvider: Render
    ClerkServerProvider->>KeylessProvider: Get keyless status
    KeylessProvider->>DriftDetection: Detect drifted keys
    DriftDetection-->>KeylessProvider: runningWithDriftedKeys
    
    rect rgb(240, 248, 255)
    note over SuspenseWhenCached: Conditional Suspense wrapping<br/>based on cacheComponents flag
    ClerkServerProvider->>SuspenseWhenCached: Wrap KeylessProvider
    SuspenseWhenCached->>SuspenseWhenCached: Check cache flag
    alt Cache enabled
        SuspenseWhenCached->>SuspenseWhenCached: Add Suspense boundary
    else Cache disabled or noopWhen=true
        SuspenseWhenCached->>SuspenseWhenCached: Skip Suspense
    end
    SuspenseWhenCached-->>ClerkServerProvider: Wrapped content
    end
    
    ClerkServerProvider->>ClientClerkProvider: Render with disableKeylessDriftDetection
    
    rect rgb(230, 245, 230)
    note over KeylessDriftDetector: Client-side lazy drift detection
    ClientClerkProvider->>KeylessDriftDetector: Mount (lazy-loaded)
    KeylessDriftDetector->>KeylessDriftDetector: Read layout segments
    KeylessDriftDetector->>KeylessDriftDetector: Check canUseKeyless flag
    alt Keyless enabled & not _not-found
        KeylessDriftDetector->>DriftDetection: Trigger detectKeylessEnvDriftAction
        DriftDetection-->>KeylessDriftDetector: Detection complete
    else Skip detection
        KeylessDriftDetector->>KeylessDriftDetector: No-op
    end
    end
    
    ClientClerkProvider-->>NextApp: Rendered tree
    NextApp-->>User: Response

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~35–50 minutes

Drift detection logic interaction: Review the bidirectional drift detection (server-side in getKeylessStatus, client-side in KeylessDriftDetector) to ensure no race conditions or duplicate detections across component boundaries.
Suspense wrapping behavior: Verify that SuspenseWhenCached correctly honors the cache flag and that noopWhen={dynamic} prevents unnecessary suspense wrapping for dynamic routes.
Telemetry per-key mechanism: Validate the refactored per-public-key flag file approach, ensure directory creation is robust, and confirm telemetry events fire correctly with the new simplified content.
Component lazy-loading path: Confirm LazyKeylessDriftDetector is imported and mounted only when keyless is enabled and not disabled via the prop.
Public API changes: Ensure the new disableKeylessDriftDetection prop propagates correctly through the provider hierarchy and that backward compatibility is maintained.

Poem

🐰 Keys that drift through the caching night,
Now detected with suspenseful might!
Lazy components whisper their call,
While servers and clients sync it all.
Next.js components embrace the change—
A hop forward, no longer strange! 🌟

Pre-merge checks and finishing touches

❌ 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%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ 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 "fix(nextjs): Improve support for cacheComponents" clearly and directly aligns with the main objective of the changeset. According to the PR objectives, this PR specifically updates Next.js-related code to improve support for cacheComponents, which is exactly what the title states. The changes across multiple files—including the addition of SuspenseWhenCached boundaries, keyless drift detection controls, and the new disableKeylessDriftDetection prop—all serve this primary goal of better supporting Next.js's cacheComponents feature. The title is concise, specific, and appropriately captures the high-level purpose without requiring detailed implementation specifics.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch elef/bill-1388-improve-experience-with-cachecomponents-and-keyless

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2025-10-31T20:34:48Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7119

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7119

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7119

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7119

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7119

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7119

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7119

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@7119

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7119

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7119

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7119

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7119

@clerk/nextjs

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

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7119

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@7119

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7119

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7119

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7119

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7119

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7119

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7119

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7119

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7119

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7119

commit: f6c4a1c

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (1)

packages/nextjs/src/app-router/client/ClerkProvider.tsx (1)
137-140: Consider extracting extended props to a proper type definition.

The props are extended inline with disableKeyless and disableKeylessDriftDetection. While functional, defining a dedicated type/interface would improve maintainability and provide better IDE support.

Consider creating a dedicated type:
type ClientClerkProviderProps = NextClerkProviderProps & {
  disableKeyless?: boolean;
  disableKeylessDriftDetection?: boolean;
};

export const ClientClerkProvider = (props: ClientClerkProviderProps) => {
  // ...
};

📜 Review details

Configuration used: Path: .coderabbit.yaml

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 f47b5a3 and f6c4a1c.

📒 Files selected for processing (7)

.changeset/quiet-rockets-invite.md (1 hunks)
packages/nextjs/src/app-router/client/ClerkProvider.tsx (2 hunks)
packages/nextjs/src/app-router/client/keyless-drift-detector.tsx (1 hunks)
packages/nextjs/src/app-router/server/ClerkProvider.tsx (2 hunks)
packages/nextjs/src/app-router/server/keyless-provider.tsx (3 hunks)
packages/nextjs/src/app-router/suspense-when-cached.tsx (1 hunks)
packages/nextjs/src/server/keyless-telemetry.ts (5 hunks)

🧰 Additional context used

📓 Path-based instructions (9)

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