fix(nextjs): Improve auth() misimport from main entry point

[alexcarpenter]

Summary

Improved developer experience when auth is accidentally imported from @clerk/nextjs instead of @clerk/nextjs/server. The auth export now includes a @deprecated JSDoc tag with a clear message guiding developers to the correct import path, visible on hover in IDEs.

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 7, 2026 0:17am

[changeset-bot]

🦋 Changeset detected

Latest commit: 140d334

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

This PR adds a deprecation notice to the auth export in packages/nextjs/src/index.ts to guide developers toward the correct import path (@clerk/nextjs/server). The deprecation is communicated via an updated JSDoc comment that will appear in IDE tooltips. A corresponding changeset file documents this patch release and explains the improved developer experience.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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 PR description clearly relates to the changeset, describing the addition of a @deprecated JSDoc tag for the auth export and the improved developer experience when auth is misimported.
Title check	✅ Passed	The title accurately summarizes the main change: improving developer experience when auth() is misimported from the main entry point by adding a deprecation notice.

_{✏️ 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: 140d334

[Ephem]

Does this approach move the error from being a build time one to being a runtime one? I'm not sure we should do that, I'd rather take a less specific error at build time than a great one at runtime or else users risk deploying bugs to production before catching the error?

I didn't think much about feasibility or where the current message was coming from when I wrote the issue. :/

[alexcarpenter]

yeah, I agree the tradeoff probably isn't worth it. losing the build-time check to improve a runtime error risks letting misimports ship to production for that subset of users.

wdyt about adding a @deprecated jsdoc notice? 140d334

[Ephem]

That's clever and likely the best we can do, I like it!

[Ephem]

I like it! 🙏

NIT: Maybe update(/remove) the PR description before merging to avoid someone being confused in the future.

[jacekradko]

FYI: I considered using the @deprecated tag, but I think it's misleading as it's not actually deprecated here: #8358