Next.js quickstart

Add Wocha sign-in to Next.js using @wocha/nextjs. The SDK implements a BFF pattern: OAuth runs server-side with a confidential client, and sessions are stored in encrypted HTTP-only cookies.

Quick start (CLI)

The recommended path scaffolds everything for you — route handler, middleware, providers, auth header, and credentials.

npx @wocha/cli init -y --framework nextjs

Generated files

Route handler

The CLI generates a zero-config handler — credentials are read from .env.local and .wocha/credentials.json:

import { createWochaHandler } from "@wocha/nextjs";
 
export const { GET, POST } = createWochaHandler();

The catch-all segment must be named wocha — the SDK reads params.wocha to route login, callback, logout, and other auth actions.

Middleware

Routes are public by default. Protect specific paths with createRouteMatcher:

import { withWochaAuth, createRouteMatcher } from "@wocha/nextjs/middleware";
 
const isProtectedRoute = createRouteMatcher([
  "/dashboard(.*)",
  "/settings(.*)",
  "/api/(?!auth)(.*)",
]);
 
export default withWochaAuth((auth, req) => {
  if (isProtectedRoute(req)) auth.protect();
});
 
export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|api/auth).*)"],
};

Layout and providers

The CLI updates your root layout to wrap the app with providers and an auth header:

"use client";
 
import { WochaSessionProvider, KeylessBanner } from "@wocha/nextjs/client";
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WochaSessionProvider>
      <KeylessBanner />
      {children}
    </WochaSessionProvider>
  );
}

"use client";
 
import { useSession } from "@wocha/nextjs/client";
 
export function WochaAuthHeader() {
  const { data, status } = useSession();
 
  if (status === "authenticated" && data?.user) {
    return (
      <header>
        <span>{data.user.email}</span>
        <a href="/api/auth/logout">Sign out</a>
      </header>
    );
  }
 
  return (
    <header>
      <a href="/api/auth/login">Sign in</a>
      <a href="/api/auth/login?screen=register">Sign up</a>
    </header>
  );
}

Your layout.tsx imports both and wraps {children} with <Providers>.

What you get

After pnpm dev:

• Auth header — Sign in and Sign up links visible on every page
• Public routes — homepage, marketing pages, and anything not matched by createRouteMatcher
• Protected routes — /dashboard/*, /settings/*, and non-auth API routes redirect to login when unauthenticated
• Hosted auth UI — users sign in at {tenant}.auth.wocha.ai and return with an encrypted session cookie

Test

1. Run pnpm dev.
2. Open http://localhost:3000 — click Sign in in the header.
3. Complete login on the hosted auth UI.
4. Confirm your email appears in the header with a Sign out link.

pnpm add @wocha/nextjs

WOCHA_CLIENT_ID=your-client-id
WOCHA_CLIENT_SECRET=your-client-secret
WOCHA_ISSUER=https://your-tenant.auth.wocha.ai
WOCHA_API_URL=https://your-tenant.api.wocha.ai  # optional
WOCHA_COOKIE_SECRET=your-cookie-secret             # optional