feat(nextjs): add helpful error for incorrect auth import

[jacekradko]

Summary

Improves developer experience when trying to import auth from the wrong path by adding a helpful TypeScript error.

Changes

• Add export declare const auth: never to main index.ts
• Include clear JSDoc with diff format showing correct import path
• Explains that auth is only available in server-side contexts

Developer Experience

Before:

'auth' is not exported from '@clerk/nextjs'

After:
TypeScript error with helpful JSDoc:

- import { auth } from '@clerk/nextjs'
+ import { auth } from '@clerk/nextjs/server'

🤖 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	Apr 20, 2026 2:28am

[changeset-bot]

🦋 Changeset detected

Latest commit: b2e4370

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: b2e4370

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 16fef271-ed20-47a8-a0d9-c94249339dd2

📥 Commits

Reviewing files that changed from the base of the PR and between e4713a8 and b2e4370.

📒 Files selected for processing (2)

• .changeset/auth-import-error.md
• packages/nextjs/src/index.ts

✅ Files skipped from review due to trivial changes (1)

• .changeset/auth-import-error.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/nextjs/src/index.ts

---

📝 Walkthrough

Walkthrough

A changeset file was added to publish a patch release for @clerk/nextjs. The package's main index now exports a new auth symbol typed as never with JSDoc explaining that auth must be imported from @clerk/nextjs/server for server-side contexts (API Routes, Server Components, Server Actions, Middleware), causing a TypeScript error if imported from the wrong path.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a TypeScript error declaration for incorrect auth imports to improve developer experience.
Description check	✅ Passed	The description is directly related to the changeset, clearly explaining the motivation, changes, and developer experience improvements for the auth import error handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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.}