feat(*): Make useAuth().getToken() throw during SSR

[Ephem]

Description

The uSES PR removed the useAuth wrapper from the nextjs package. That wrapper made getToken be undefined in server environments, and removing that caused calling useAuth().getToken() to stall forever during server-side rendering.

This PR tackles this at the react package level instead, since it's a common concern. During server-side rendering, getToken is now a function that throws a clerk_runtime_not_browser error.

The error aligns with this PR: Make gettoken callable outside of react

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

• Breaking Changes

  • useAuth().getToken now throws an error in non-browser environments instead of returning undefined. Wrap calls in try/catch or use only within browser contexts (useEffect, event handlers, or non-suspenseful data fetching). Server-side token access requires using the Auth object instead.

• Documentation

  • Updated guidance and error messages for server-side rendering token retrieval scenarios.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Feb 2, 2026 2:06pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 678b5e5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@clerk/react	Major
@clerk/nextjs	Major
@clerk/react-router	Major
@clerk/tanstack-react-start	Minor
@clerk/shared	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/clerk-js	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nuxt	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	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

The changes implement SSR-safety for the useAuth().getToken function across multiple Clerk React packages. A browser environment check is added to throw a ClerkRuntimeError when getToken is invoked in non-browser contexts. The changelog documents breaking version changes and migration guidance, including updated error messages that provide reference documentation for server-side auth access. Tests verify the error-throwing behavior. JSDoc comments are expanded to document the throw contract and server-side access patterns.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR successfully addresses USER-4554 by implementing SSR-safe behavior for useAuth().getToken() that throws instead of hanging.
Out of Scope Changes check	✅ Passed	All changes are directly related to the objective of making useAuth().getToken() SSR-safe; no unrelated modifications detected.
Title check	✅ Passed	The title clearly and specifically describes the main change: making useAuth().getToken() throw during SSR, which is the primary objective of this PR.

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

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 678b5e5

[Ephem]

!allow-major