@kolaylogin/nextjs

Next.js SDK for KolayLogin. Ships middleware for the App Router edge runtime, a server-side session reader for Route Handlers and Server Components, and typed helpers that sit directly on top of @kolaylogin/backend.

Install

npm install @kolaylogin/nextjs

Next.js 14+ (App Router) and Node 20+.

Middleware (edge)

Protect routes globally with one import. The middleware verifies the __session JWT at the edge — no database or origin round-trip.

// middleware.ts
import type { NextRequest } from 'next/server';
import { requireSessionMiddleware } from '@kolaylogin/nextjs';

export async function middleware(req: NextRequest) {
  return await requireSessionMiddleware(req, {
    baseUrl: process.env.KL_API_BASE_URL!,
    issuer: process.env.KL_JWT_ISSUER,
    redirectTo: '/sign-in',
  });
}

export const config = {
  matcher: ['/app/:path*', '/api/private/:path*'],
};

Unauthenticated requests to matched routes are redirected to redirectTo (or return a 401 for /api/* paths). The signed-in user's claims are forwarded as x-kl-user-id and x-kl-env-id headers so downstream handlers can read them without re-verifying.

Server Components & Route Handlers

// app/api/me/route.ts
import { NextResponse } from 'next/server';
import { getSessionFromNextRequest } from '@kolaylogin/nextjs';

export async function GET(req: Request) {
  const session = await getSessionFromNextRequest(req, {
    baseUrl: process.env.KL_API_BASE_URL!,
    issuer: process.env.KL_JWT_ISSUER,
  });
  if (!session) return NextResponse.json({ error: 'unauthenticated' }, { status: 401 });

  return NextResponse.json({ userId: session.sub });
}

API

requireSessionMiddleware(req, options)

| Option | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------------------------------------ | | baseUrl | string | yes | Instance API base URL. | | issuer | string | no | Expected iss. Strongly recommended in production. | | audience | string | no | Expected aud, if set. | | redirectTo | string | no | Where to send unauthenticated requests. When omitted, returns 401 with a JSON body. | | publicPaths | string[] | no | Skip session enforcement for these paths (e.g. ['/health']). |

getSessionFromNextRequest(req, options)

Pulls the __session cookie out of the request, verifies it, and returns the claims. Returns null when no cookie is present. Throws on an invalid token.

Environment variables

Minimum set to wire up:

KL_API_BASE_URL=https://auth.example.com
KL_JWT_ISSUER=https://auth.example.com/

How it integrates with @kolaylogin/react

Browser-side: @kolaylogin/react reads __session from cookies, exposes it via hooks, and refreshes it automatically.

Edge/server-side: @kolaylogin/nextjs re-verifies the same cookie in middleware and Server Components for defence-in-depth — a compromised browser cookie is rejected at the edge because JWKS verification still runs.

You will almost always install both in a Next.js app.

License

MIT