Next.js SDK

@wocha/nextjs is the Next.js App Router adapter for Wocha. It implements a BFF (backend-for-frontend) pattern: OAuth runs server-side with a confidential client, and sessions are stored in encrypted HTTP-only cookies.

Installation

pnpm add @wocha/nextjs

Or scaffold with the CLI

npx @wocha/cli init --framework nextjs

Peer dependencies: Next.js 14+, React 18+.

Environment variables

.env.local

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

Route handler

app/api/auth/[...wocha]/route.ts

import { createWochaHandler } from "@wocha/nextjs";
 
export const { GET, POST } = createWochaHandler({
  clientId: process.env.WOCHA_CLIENT_ID!,
  clientSecret: process.env.WOCHA_CLIENT_SECRET!,
  issuer: process.env.WOCHA_ISSUER!,
});

When env vars are set, you can omit the config object:

export const { GET, POST } = createWochaHandler();

Middleware

middleware.ts

import { withWochaAuth } from "@wocha/nextjs/middleware";
 
export default withWochaAuth(undefined, {
  publicPaths: ["/", "/about"],
});

Expired access tokens are refreshed silently using the refresh token before redirecting to login.

Server helpers

Use server-side helpers in Server Components and route handlers:

import { getSession, getAccessToken } from "@wocha/nextjs";
 
export default async function DashboardPage() {
  const session = await getSession();
  if (!session) redirect("/api/auth/login");
  return <h1>Hello {session.user.name}</h1>;
}

Client hooks

Wrap your layout with WochaSessionProvider and use client hooks:

"use client";
import { useSession } from "@wocha/nextjs/client";
 
const { data, status } = useSession();

Learn more

Next.js quickstart
React SDK — for SPAs without a server BFF