feat(testing): Add nextjs cache components test app

[jacekradko]

Summary

Adds integration test app for Next.js 16 cache components feature to validate Clerk's auth() behavior with the new cacheComponents config.

Test Scenarios

• auth() in server components, server actions, and API routes
• "use cache" correct pattern (auth outside, userId passed in)
• "use cache" error documentation
• PPR with auth()
• Protected routes via proxy

Key Findings

• ClerkProvider must be wrapped in <Suspense> for cache components to work
• auth() inside "use cache" functions produces build-time error
• Route segment configs (dynamic) incompatible with cacheComponents
• Next.js 16 moved experimental.ppr to top-level cacheComponents

Files Added

• integration/templates/next-cache-components/ - Full test app
• integration/tests/cache-components.test.ts - E2E tests
• Updated integration/presets/next.ts with cacheComponents preset

Test plan

• Run e2e tests: pnpm test:integration:next-cache-components
• Verify build passes: cd integration/templates/next-cache-components && pnpm build

Summary by CodeRabbit

• New Features

  • Added a complete integration test app demonstrating Next.js experimental cache components with Clerk auth: pages for auth in server components, server actions, API checks, PPR, protected routes, and correct/error cache patterns; includes README, styles, config, and middleware.

• Tests

  • Added an end-to-end Playwright test suite covering all scenarios.

• Chores

  • Registered a new template/preset, added a long-running app entry, and an integration test script plus CI matrix entry.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 4, 2026 2:29am

[changeset-bot]

⚠️ No Changeset found

Latest commit: d743c60

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new Next.js integration template next-cache-components and registers a preset next.cacheComponents (exported from integration/presets/next.ts). Introduces a test app under integration/templates/next-cache-components (pages, API route, proxy middleware, next.config.js with cacheComponents enabled, package.json, tsconfig.json, globals.css, RootLayout). Adds integration tests (integration/tests/cache-components.test.ts), a long-running app entry, a package script test:integration:cache-components, and a CI matrix entry for the cache-components integration.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.32% 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 accurately describes the main change: adding a new integration test application for Next.js cache components, which is the primary purpose of this PR.

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

---

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7728

@clerk/upgrade

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

@clerk/vue

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

commit: d743c60