Skip to content

Conversation

@alexcarpenter
Copy link
Member

@alexcarpenter alexcarpenter commented Nov 20, 2025

Description

Screenshot 2025-11-20 at 11 46 38 AM

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
Copy link

changeset-bot bot commented Nov 20, 2025

🦋 Changeset detected

Latest commit: 26f15d6

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
Copy link

vercel bot commented Nov 20, 2025

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

Project Deployment Preview Comments Updated (UTC)
clerk-js-sandbox Ready Ready Preview Comment Nov 20, 2025 4:41pm

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 20, 2025

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
Loading

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.
✨ 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 alexcarpenter/update-middleware-location-check-for-proxy

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

@pkg-pr-new
Copy link

pkg-pr-new bot commented Nov 20, 2025

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: 26f15d6

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 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 5068f1c and a8ba666.

📒 Files selected for processing (3)
  • packages/nextjs/src/app-router/server/auth.ts (2 hunks)
  • packages/nextjs/src/server/fs/middleware-location.ts (3 hunks)
  • packages/nextjs/src/utils/sdk-versions.ts (1 hunks)
🧰 Additional context used
🧬 Code graph analysis (2)
packages/nextjs/src/app-router/server/auth.ts (1)
packages/nextjs/src/utils/sdk-versions.ts (1)
  • isNext16OrHigher (16-16)
packages/nextjs/src/server/fs/middleware-location.ts (3)
packages/nextjs/src/utils/sdk-versions.ts (1)
  • isNext16OrHigher (16-16)
packages/nextjs/src/runtime/node/safe-node-apis.js (1)
  • path (7-7)
packages/nextjs/src/runtime/browser/safe-node-apis.js (1)
  • path (5-5)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
  • GitHub Check: Formatting | Dedupe | Changeset
  • GitHub Check: semgrep-cloud-platform/scan
  • GitHub Check: semgrep-cloud-platform/scan
  • GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (7)
packages/nextjs/src/app-router/server/auth.ts (2)

14-14: LGTM!

The import of isNext16OrHigher is correctly added alongside the existing isNextWithUnstableServerActions import.


84-85: LGTM!

The conditional filename logic correctly adapts the error message based on the Next.js version, guiding users to the appropriate middleware or proxy file location.

packages/nextjs/src/utils/sdk-versions.ts (1)

16-16: LGTM!

The export statement correctly includes isNext16OrHigher alongside the existing version detection exports.

packages/nextjs/src/server/fs/middleware-location.ts (4)

1-1: LGTM!

The import of isNext16OrHigher is correctly added to enable Next.js version-aware file detection.


16-18: LGTM!

The conditional logic correctly handles both middleware and proxy files for Next.js 16+ while maintaining backward compatibility. The inline comment clearly explains the dual-runtime support.


20-26: LGTM!

The suggestionMessage function is correctly updated to accept a dynamic fileName parameter and uses fileNameDisplay for user-facing generic references while using the specific fileName in the file path. This properly supports both middleware and proxy files.


35-48: LGTM!

The checkMiddlewareLocation function correctly iterates over both file names and extensions, returning a suggestion message with the actual filename on the first match. The nested loop structure ensures all valid combinations are checked.

Comment on lines +11 to +14
/**
* Next.js 16+ renamed middleware.ts to proxy.ts
*/
const isNext16OrHigher = nextPkg.version.startsWith('16.') || parseInt(nextPkg.version.split('.')[0]) >= 16;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Correct the misleading JSDoc comment.

The JSDoc states that Next.js 16+ "renamed" middleware.ts to proxy.ts, but this is contradicted by the implementation in middleware-location.ts (line 16), which explicitly states that both files are supported: "Next.js 16+ supports both middleware.ts (Edge runtime) and proxy.ts (Node.js runtime)". The code also checks for both filenames in the array ['middleware', 'proxy'].

Update the JSDoc to accurately reflect that both files are supported:

 /**
- * Next.js 16+ renamed middleware.ts to proxy.ts
+ * Next.js 16+ introduced proxy.ts (Node.js runtime) alongside middleware.ts (Edge runtime)
  */
 const isNext16OrHigher = nextPkg.version.startsWith('16.') || parseInt(nextPkg.version.split('.')[0]) >= 16;
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
/**
* Next.js 16+ renamed middleware.ts to proxy.ts
*/
const isNext16OrHigher = nextPkg.version.startsWith('16.') || parseInt(nextPkg.version.split('.')[0]) >= 16;
/**
* Next.js 16+ introduced proxy.ts (Node.js runtime) alongside middleware.ts (Edge runtime)
*/
const isNext16OrHigher = nextPkg.version.startsWith('16.') || parseInt(nextPkg.version.split('.')[0]) >= 16;
🤖 Prompt for AI Agents
In packages/nextjs/src/utils/sdk-versions.ts around lines 11 to 14, the JSDoc
incorrectly states that Next.js 16+ "renamed middleware.ts to proxy.ts"; update
the comment to accurately state that Next.js 16+ supports both middleware.ts
(Edge runtime) and proxy.ts (Node.js runtime) or that both filenames are
supported, so it aligns with middleware-location.ts and the code that checks
['middleware','proxy'].

@alexcarpenter
Copy link
Member Author

!snapshot

@clerk-cookie
Copy link
Collaborator

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

/**
* Next.js 16+ renamed middleware.ts to proxy.ts
*/
const isNext16OrHigher = nextPkg.version.startsWith('16.') || parseInt(nextPkg.version.split('.')[0]) >= 16;
Copy link
Member

@jacekradko jacekradko Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should add tests for this boolean expression (it kind of feels like a function)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, we can make it a bit more robust for the future:

function meetsNextMinimumVersion(nextPkg, minimumMajorVersion = 16) {
  if (!nextPkg?.version) {
    return false;
  }
  
  const majorVersion = parseInt(nextPkg.version.split('.')[0], 10);
  return !isNaN(majorVersion) && majorVersion >= minimumMajorVersion;
}

const isNext16OrHigher = meetsNextMinimumVersion(nextPkg, 16);

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants