Skip to content

Export ConvexAuthNextjsProvider so apps own the Convex client under SSR - #780

Draft
erquhart wants to merge 3 commits into
rebootfrom
nextjs-client-provider-export
Draft

erquhart wants to merge 3 commits into
rebootfrom
nextjs-client-provider-export

Conversation

@erquhart

@erquhart erquhart commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

This PR splits the server and client providers for Next.js, replacing the single provider that rendered the client itself. This wraps reading the initial token from cookie inside the server provider and requires the app to pass in its own Convex client so it can be directly configured, following prior art. Any future server behavior we want to add in addition to reading the token cookie can now be added within the server provider with the option of avoiding userland changes.

Also snuck in route configurability since we were messing with server setup anyway.

Note that this is a breaking change for Next.js users, updating requires using ConvexAuthNextJsProvider, passing in their Convex client, and wrapping the app with ConvexAuthNextJsServerProvider.

`ConvexAuthNextjsServerProvider` rendered the client provider itself and
built the `ConvexReactClient` internally, so a Next app couldn't supply its
own client: no `ConvexQueryClient` (TanStack Query), no client options, no
use of the client outside React. A `ConvexReactClient` can't cross the
Server Component boundary, so a `client` prop on the server provider was
never an option.

Follow v1's split instead. The server provider now reads the cookie and
renders a small client context carrying what it knows (the access token,
the auth route paths). `ConvexAuthNextjsProvider`, exported at the new
`@convex-dev/auth/ssr/nextjs/client` entry, reads that context, so the app
renders it from its own `ConvexClientProvider.tsx` with its own client,
the same file the Convex Next.js quickstart already has.

`setupConvexAuthNextjs` takes `routes` for handlers mounted away from
`/auth/*`, resolving the TODO on the server provider; the paths travel in
the same context.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RuiNWRbC1cfyoU7jnDzisM
@vercel

vercel Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
auth-v2 Ready Ready Preview Oct 23, 2026 4:23am UTC
1 Skipped Deployment
Project Deployment Actions Updated
convex-auth-docs Ignored Ignored Oct 23, 2026 4:23am UTC

Request Review

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 10 files

Tip: Get a Slack DM when cubic finishes reviewing your PRs. Connect Slack

Re-trigger cubic

Comment thread packages/core/src/ssr/nextjs/client.tsx Outdated
Comment thread packages/core/src/ssr/nextjs/provider.test.tsx
@erquhart
erquhart marked this pull request as draft October 22, 2026 17:23
Drop the comments that explained the PR rather than the code, restore the
original prop docs, and put "replaces ConvexAuthProvider" back in the setup
docs.

`??=` treated an explicit `initialToken={null}` as omitted and adopted the
server state's token. Fall through only on `undefined`, and make the test
read the token after the auth client's init, where the regression shows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RuiNWRbC1cfyoU7jnDzisM
@pkg-pr-new

pkg-pr-new Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
npm i https://pkg.pr.new/@convex-dev/auth@780

commit: cf9ccc3

The server provider no longer passes `convexUrl`, so the client-less path of
`ConvexAuthNextjsProvider` fell back to `NEXT_PUBLIC_CONVEX_URL` only. The
app owns the client now, so make `client` required and drop `convexUrl`.

The "starts signed out" test read the token before init; wait for
`isLoading` to clear, as the precedence test does.

Point the routes step of the setup docs at the `routes` config.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RuiNWRbC1cfyoU7jnDzisM

This branch was successfully deployed

1 active deployment
Preview – auth-v2 — cf9ccc3d Deployed Oct 23, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants