ssr/nextjs

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

Server bindings for Convex Auth on Next.js (App Router), exported at @convex-dev/auth/ssr/nextjs.

This is the thin, genuinely Next-specific layer. The auth handlers (per-method sign-in, plus refresh/sign-out) are framework-agnostic (Request) => Response functions mounted directly as route handlers (see @convex-dev/auth/ssr). What remains Next-specific is the proxy (up-front refresh + redirects), reading the access token in Server Components, and the server-side provider that hydrates the client.

Interfaces

• ConvexAuthNextjsConfig
• ConvexAuthNextjsProxyCtx

Type Aliases

ConvexAuthNextjsProxyHandler

type ConvexAuthNextjsProxyHandler = (
  request,
  ctx,
) => Promise<NextResponse | undefined | void> | NextResponse | undefined | void;

A proxy handler: inspect the request, optionally return a response (e.g. a redirect) to short-circuit.

Parameters

Parameter	Type
request	NextRequest
ctx	ConvexAuthNextjsProxyCtx

Returns

| Promise<NextResponse | undefined | void> | NextResponse | undefined | void

Functions

setupConvexAuthNextjs()

function setupConvexAuthNextjs(config): object;

Build the Next.js server helpers from one config.

export const {
  convexAuthNextjsProxy,
  nextjsProxyRedirect,
  convexAuthNextjsAccessToken,
  isAuthenticatedNextjs,
  ConvexAuthNextjsServerProvider,
} = setupConvexAuthNextjs({
  convexUrl: process.env.NEXT_PUBLIC_CONVEX_URL!,
  refreshSession: api.auth.refreshSession,
  isAuthenticated: api.auth.isAuthenticated,
});

Parameters

Parameter	Type
config	ConvexAuthNextjsConfig

Returns

convexAuthNextjsAccessToken

convexAuthNextjsAccessToken: () => Promise<string | null>;

The current access token in a Server Component, or null. Never triggers a refresh (the proxy does that); returns null for an expired token.

The token is returned after only a local expiry check, not a signature check — that is safe because its only use is to authenticate a request to the Convex backend (e.g. preloadQuery), which verifies the signature itself. To decide authentication state server-side, use isAuthenticatedNextjs instead, which verifies against the backend.

Returns

Promise<string | null>

convexAuthNextjsProxy

convexAuthNextjsProxy: (handler?) => (request) =>
  Promise<NextResponse<unknown>>;

Build a Next.js proxy (proxy.ts) that refreshes the session up front (so downstream Server Components see a fresh token) and optionally runs redirect logic.

Parameters

Parameter	Type
handler?	ConvexAuthNextjsProxyHandler

Returns

(request) => Promise<NextResponse<unknown>>

ConvexAuthNextjsServerProvider

ConvexAuthNextjsServerProvider: (__namedParameters) => Promise<Element>;

Server Component that reads the cookie token and renders the client provider, so the client hydrates ready to authenticate.

Parameters

Parameter	Type
__namedParameters	{ children: ReactNode; }
__namedParameters.children	ReactNode

Returns

Promise<Element>

isAuthenticatedNextjs

isAuthenticatedNextjs: () => Promise<boolean>;

Whether the current request carries a valid, signed-in session. Verifies the cookie's access token against the backend (which checks its signature), so a forged cookie can't fake authentication.

Returns

Promise<boolean>

nextjsProxyRedirect

nextjsProxyRedirect: (request, path) => NextResponse;

Redirect helper for use inside a proxy handler.

Part of the API returned from setupConvexAuthNextjs.

Parameters

Parameter	Type
request	NextRequest
path	string

Returns

NextResponse