Next.js SDK

The Next.js SDK wires App Router applications through one server-side middleware path.

Recommended path

Let the CLI generate this setup first. Manual setup is useful when reviewing or adapting the generated files.

Install

pnpm add @zitadel/sdk-next

npm install @zitadel/sdk-next

yarn add @zitadel/sdk-next

Setup

The CLI adds the SDK package, creates auth routes, writes a profile page, and installs middleware that runs nextgenMiddleware.

app/login/page.tsx

app/register/page.tsx

app/profile/page.tsx

middleware.ts

package.json

Create src/proxy.ts at the root of your Next.js app and call the middleware:

import { nextgenMiddleware } from "@zitadel/sdk-next/middleware";
import type { NextRequest } from "next/server";

export function proxy(req: NextRequest) {
  return nextgenMiddleware(req, {
    url: process.env.ZITADEL_URL,
    protectedRoutes: ["/profile"],
    loginPath: "/login",
  });
}

export const config = {
  matcher: ["/__nextgen/:path*", "/profile", "/login"],
};

Runtime model

Proxy /__nextgen/* requests to the Zitadel backend.

Verify the session JWT via JWKS using Web Crypto.

Redirect unauthenticated users from protected routes to loginPath.

Usage

Read auth state in a server component:

import { auth } from "@zitadel/sdk-next";

export default async function Page() {
  const session = await auth();
  if (!session.isAuthenticated) return <p>Not signed in</p>;

  return <p>Hello {session.session.email}</p>;
}

Verify

Start the app with the generated environment.
Visit /login and register a user.
Confirm /profile is reachable after login.
Log out and confirm /profile redirects back to /login.