feat(react): Remove initialAuthState option from useAuth

[Ephem]

Description

Note

Keeping this with the do not merge label until I've done some more testing and verifying.

This PR refactors the React ClerkProvider by introducing a new InitialAuthStateProvider, and moves resolving the correct initialState | state down into the useAuth hook. This is a first step towards moving more logic down into the hooks.

This PR also refactors the ClerkProvider in @clerk/nextjs to not rely on PromisifiedAuthContext and removes the usePromisifiedAuth. When nesting two providers like this:

<ClerkProvider>
  <ClerkProvider dynamic>

The inner provider does not render the React ClerkProvider. For this specific case, the PromisifiedAuthContext was fulfilling a role as a separate initial state context. This PR instead uses the new InitialAuthStateProvider directly for this use case.

The usePromisifiedAuth hook was the only place useAuth(initialAuthState) was being used, an option specifically option, we now rely on the internal <InitialAuthStateProvider> instead.

This is technically a breaking change, but I expect few if any users to be relying on this option, the encouraged way to populate auth state ahead of Clerk loading on the client is to do it at the <ClerkProvider> level.

We are planning improvements around how hydration of the auth state works, and keeping the API surface small and implementation complexity low will help with that.

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:

[changeset-bot]

🦋 Changeset detected

Latest commit: 19b996b

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

This PR includes changesets to release 7 packages

Name	Type
@clerk/react	Major
@clerk/expo	Major
@clerk/nextjs	Major
@clerk/react-router	Major
@clerk/tanstack-react-start	Major
@clerk/chrome-extension	Patch
@clerk/elements	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]

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Nov 19, 2025 6:06pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fredrik/remove-initial-auth-state

---

_{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@7194

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7194

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7194

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 19b996b