feat(nextjs,react,shared): Support suspenseful initialState

[Ephem]

Description

This PR adds internal support for initialState: Promise<InitialState> and uses that in the Next SDK when <ClerkProvider dynamic>.

This avoids having to await it in the top level provider, instead moving that down to where the initialState is actually being consumed, the hooks. This is done via the React.use hook, which is only supported in React 19, which all Next versions core3 supports already relies on.

Given that initialState currently only comes from a header, this might not seem like a consequential change, but it helps with two things:

• For improved cacheComponents support, we want to move everything dynamic out of the ClerkProvider down to where things are actually used. This would also avoid users having to wrap the <ClerkProvider> in a <Suspense> boundary, instead being able to place those further down.
  • This PR does not enable that, it is only a step on the way
• In the future, we might want to support other types of initialState, and not blocking at the top level will be beneficial then

Summary by CodeRabbit

• New Features

  • Provider now accepts promise-based initial state, allowing asynchronous state initialization in apps running on React 19+.

• Improvements

  • Added runtime validation to block promise-based initial state on unsupported React versions and surface clearer error messages.

• Chores

  • Version bumps for related packages.

[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 5, 2026 10:18am

[changeset-bot]

🦋 Changeset detected

Latest commit: da1ede7

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

This PR includes changesets to release 20 packages

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

This pull request adds support for Promise<InitialState> alongside InitialState across the Clerk provider stack. The Next.js ClerkProvider no longer awaits initialState and may pass a promise through to context. Shared context types and providers are updated to accept InitialState | Promise<InitialState>, and hooks resolve the promise using React 19's React.use when available. A runtime check throws if a promise is provided on React versions that lack the required API.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.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
Title check	✅ Passed	The title 'Support suspenseful initialState' accurately reflects the main change - enabling Promise-based initialState across packages.
Linked Issues check	✅ Passed	The PR implements the key objective from USER-4499: allowing initialState to be a Promise and deferring awaiting to hook usage locations.
Out of Scope Changes check	✅ Passed	All changes directly support Promise-based initialState handling; no unrelated modifications detected beyond the intended scope.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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@7759

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: da1ede7

[Ephem]

This PR in itself should not change the public behavior since we are still awaiting another header (nonce) in the provider. When we fix that, it will sometimes move where things suspend which is worthy of a proper changeset.

[jacekradko]

Nice work! Looks ready to go, but let's make an issue to come back and ensure we backfill any test coverage

[Ephem]

@jacekradko Thanks! I chose not to include that here since the public behavior didn't change as part of this PR. I could have included some unit tests but not sure those are very valuable here so kind of want to figure out the whole thing first.

I went ahead and created a ticket to not forget. 👍