chore(nextjs): Update middleware check for proxy usage

[alexcarpenter]

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

• [ ] 🐛 Bug fix
• [ ] 🌟 New feature
• [ ] 🔨 Breaking change
• [ ] 📖 Refactoring / dependency upgrade / documentation
• [ ] other:

Summary by CodeRabbit

• New Features

  • Added automatic detection and support for Next.js 16+ projects.

• Improvements

  • Guidance and onboarding messages for middleware/proxy configuration now adapt to your Next.js version, offering version-appropriate file location suggestions.

• Chores

  • Release metadata updated to include this patch.

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

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: b60616efa2126ddda39251aa4bc19e3dcf31b10a

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[bot]]

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

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jan 7, 2026 2:22pm

[coderabbitai[bot]]

[!IMPORTANT]

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

Adds Next.js 16+ detection and uses it to treat proxy.(ts|js) alongside middleware.(ts|js) when generating messages and searching for existing files; introduces isNext16OrHigher and updates auth and middleware-location logic to branch on it.

Changes

Cohort / File(s)	Summary
Next.js SDK version flag packages/nextjs/src/utils/sdk-versions.ts	Adds exported constant isNext16OrHigher (true for Next.js v16.x or higher) and includes it in the module exports.
Middleware / proxy handling packages/nextjs/src/app-router/server/auth.ts, packages/nextjs/src/server/fs/middleware-location.ts	Import and use isNext16OrHigher; determine file name set (['middleware','proxy'] for v16+, otherwise ['middleware']), iterate over names and extensions when searching for existing files, and use chosen fileName in user-facing suggestion text.
Changeset .changeset/tangy-sides-crash.md	Adds changeset declaring patch release noting middleware location check now accounts for proxy.ts in Next 16+.

Sequence Diagram(s)

sequenceDiagram
  participant Caller as CLI / runtime
  participant SDK as packages/nextjs
  participant FS as filesystem search
  rect rgb(230,245,255)
    Note over SDK: Determine Next.js major version
    SDK->>SDK: evaluate isNext16OrHigher
  end
  alt Next.js >= 16
    SDK->>FS: search for files in ['middleware','proxy'] x ['.ts','.js']
  else Next.js < 16
    SDK->>FS: search for files in ['middleware'] x ['.ts','.js']
  end
  FS-->>SDK: return first match or none
  alt found
    SDK->>Caller: show suggestion message including found fileName and path
  else not found
    SDK->>Caller: show suggestion message referencing expected fileName(s)
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Heterogeneous changes: new exported constant plus branching logic in two modules.
• Areas to check closely:
  • Version parsing logic in sdk-versions.ts for edge cases (pre-release, non-semver).
  • Correct iteration and early-exit behavior in middleware-location.ts (first match selection).
  • Message string construction in auth.ts to ensure path formatting and pluralization are correct.

Poem

🐰
I sniff the code where versions hop,
Sixteen brings proxies to the top.
I found the file, I pointed true,
A tiny hop to guide you through. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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
Title check	✅ Passed	The title accurately describes the main change: updating middleware location checks to support proxy files in Next.js 16+, which aligns with the core modifications across all three source files and the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

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

[pkg-pr-new[bot]]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

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

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

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

@clerk/types

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

@clerk/upgrade

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

@clerk/vue

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

commit: b60616e

[alexcarpenter]

!snapshot

[clerk-cookie]

Hey @alexcarpenter - the snapshot version command generated the following package versions:

Package	Version
@clerk/agent-toolkit	0.2.3-snapshot.v20251120164403
@clerk/astro	2.16.1-snapshot.v20251120164403
@clerk/backend	2.23.1-snapshot.v20251120164403
@clerk/chrome-extension	2.8.3-snapshot.v20251120164403
@clerk/clerk-js	5.109.1-snapshot.v20251120164403
@clerk/elements	0.23.84-snapshot.v20251120164403
@clerk/clerk-expo	2.19.3-snapshot.v20251120164403
@clerk/expo-passkeys	0.4.20-snapshot.v20251120164403
@clerk/express	1.7.51-snapshot.v20251120164403
@clerk/fastify	2.6.3-snapshot.v20251120164403
@clerk/localizations	3.28.2-snapshot.v20251120164403
@clerk/nextjs	6.35.3-snapshot.v20251120164403
@clerk/nuxt	1.13.1-snapshot.v20251120164403
@clerk/clerk-react	5.56.1-snapshot.v20251120164403
@clerk/react-router	2.2.3-snapshot.v20251120164403
@clerk/remix	4.13.18-snapshot.v20251120164403
@clerk/shared	3.35.1-snapshot.v20251120164403
@clerk/tanstack-react-start	0.27.3-snapshot.v20251120164403
@clerk/testing	1.13.17-snapshot.v20251120164403
@clerk/themes	2.4.38-snapshot.v20251120164403
@clerk/types	4.101.1-snapshot.v20251120164403
@clerk/vue	1.16.1-snapshot.v20251120164403

Tip: Use the snippet copy button below to quickly install the required packages. @clerk/agent-toolkit

npm i @clerk/[email protected] --save-exact

@clerk/astro

npm i @clerk/[email protected] --save-exact

@clerk/backend

npm i @clerk/[email protected] --save-exact

@clerk/chrome-extension

npm i @clerk/[email protected] --save-exact

@clerk/clerk-js

npm i @clerk/[email protected] --save-exact

@clerk/elements

npm i @clerk/[email protected] --save-exact

@clerk/clerk-expo

npm i @clerk/[email protected] --save-exact

@clerk/expo-passkeys

npm i @clerk/[email protected] --save-exact

@clerk/express

npm i @clerk/[email protected] --save-exact

@clerk/fastify

npm i @clerk/[email protected] --save-exact

@clerk/localizations

npm i @clerk/[email protected] --save-exact

@clerk/nextjs

npm i @clerk/[email protected] --save-exact

@clerk/nuxt

npm i @clerk/[email protected] --save-exact

@clerk/clerk-react

npm i @clerk/[email protected] --save-exact

@clerk/react-router

npm i @clerk/[email protected] --save-exact

@clerk/remix

npm i @clerk/[email protected] --save-exact

@clerk/shared

npm i @clerk/[email protected] --save-exact

@clerk/tanstack-react-start

npm i @clerk/[email protected] --save-exact

@clerk/testing

npm i @clerk/[email protected] --save-exact

@clerk/themes

npm i @clerk/[email protected] --save-exact

@clerk/types

npm i @clerk/[email protected] --save-exact

@clerk/vue

npm i @clerk/[email protected] --save-exact