fix(nextjs): add runtime error for auth() misimport from main entry point

[alexcarpenter]

Summary

• When importing auth from @clerk/nextjs instead of @clerk/nextjs/server, the bundler previously showed a generic 'auth' is not exported from '@clerk/nextjs' error with no hint about the correct import path
• Replaces the type-only declare const auth: never stub with a real runtime Proxy that throws a descriptive error: Clerk: auth() was imported from '@clerk/nextjs'. The auth() helper is a server-side function and must be imported from '@clerk/nextjs/server'.
• The Proxy catches both function calls (auth()) and property access (auth.protect), so the helpful error surfaces regardless of how the developer uses the misimported binding

BEFORE	AFTER

Ref: SDK-65

Test plan

• Added auth-misimport.test.ts covering both function call and property access scenarios
• Existing server exports snapshot test still passes
• Verify in a Next.js app that import { auth } from '@clerk/nextjs' shows the new error instead of the bundler error

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 6, 2026 2:55pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 7e031ec

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces the public auth export in packages/nextjs/src/index.ts with a re-export from a new server-only-stubs module. Adds server-only-stubs.ts which exports auth as a Proxy that throws descriptive runtime errors on function invocation or property access, directing callers to import from @clerk/nextjs/server. Adds tests in packages/nextjs/src/tests/auth-misimport.test.ts that assert the thrown error messages for both call and property-access patterns. Adds a changeset documenting the runtime error message change.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding a runtime error for auth() misimport from the main entry point, which is the primary focus of this PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description clearly explains the problem, solution, and changes made, with before/after screenshots and test coverage details.

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[alexcarpenter]

!snapshot

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8487

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 7e031ec