Next.js

@better-iam/next integrates Better IAM with the Next.js 15 App Router (React 19). The App Router spreads a request across server components, layouts, route handlers, server actions, and middleware, and each exposes the request differently: headers() and cookies() in components, a Request in route handlers, form data in actions, and an edge runtime without database access in middleware. Calling the core API directly would mean building the credential, redirecting with a safe ?next=, mapping refusals to status codes, and writing session cookies by hand in each of those places. One createIamNext(iam) call does it once and gives your server code:

• Sessions in server components: getSession() and requireSession(), memoized per request.
• Guards: page() for pages and layouts, route() and apiRoute() for route handlers, action() for server actions, and require() for one-off checks.
• Rendering by permission: can(), allowed(), and the <iamNext.Can> server component, batched into one authorizeMany per request.
• A server-side typed client: client() calls the IAM handler in process and writes the cookies it issues, so server actions can sign people in and out without client JavaScript.
• Cross-site checks: route(), apiRoute(), and pages.api() refuse cookie-authenticated mutations sent by another site's page (details). Next checks server actions itself.
• Hydration: sessionForClient() hands the session to IamNextProvider, so client components render the signed-in person on the first pass, matching the server's HTML (Client components).
• Auth forms: drop-in server actions and unstyled, accessible forms for sign-in, MFA, step-up, password reset, sign-up, email verification, and invitations.
• Organizations in the URL, edge middleware, step-up, service credentials, webhooks and assertions, background delivery, and the Pages Router.

The package has three entries:

The umbrella package exposes the same entries as better-iam/next, better-iam/next/edge, and better-iam/next/client.

Install

npm i @better-iam/next @better-iam/client @better-iam/server @better-iam/adapter-sqlite

Or install the umbrella package, better-iam, and import from its subpaths. See Installation for other storage adapters.

Application layout

A complete App Router setup spreads over these files. The instance, the helpers, and the API route are the minimum; the others add edge redirects, drop-in forms, and background delivery.

Setup

import { betterIam } from '@better-iam/server';
import { sqliteAdapter } from '@better-iam/adapter-sqlite';

export const iam = betterIam({
  database: sqliteAdapter({ filename: process.env.BETTER_IAM_DATABASE ?? '.data/iam.db' }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: process.env.BETTER_IAM_BASE_URL ?? 'http://localhost:3000',
  permissions: { actions: ['documents:read', 'documents:write'] },
});

import { createIamNext } from '@better-iam/next';
import { iam } from './iam';

export const iamNext = createIamNext(iam, {
  loginPath: '/login',
  stepUpPath: '/reauth',
  interrupts: 'forbidden', // denials render app/forbidden.tsx
});

import { iamNext } from '@/lib/iam-next';

export const runtime = 'nodejs';
export const { GET, POST, OPTIONS } = iamNext.handlers();

/** @type {import('next').NextConfig} */
export default {
  serverExternalPackages: [
    '@better-iam/server',
    '@better-iam/auth',
    '@better-iam/adapter-sqlite',
    'argon2',
    'better-sqlite3',
  ],
  experimental: { authInterrupts: true }, // only for interrupts: true or 'forbidden'
};

import { NextResponse } from 'next/server';
import { createIamMiddleware } from '@better-iam/next/edge';

export const middleware = createIamMiddleware({
  loginPath: '/login',
  publicPaths: ['/', '/pricing', '/docs/**', '/invite/*'],
  next: (init) => NextResponse.next(init),
});
export const config = { matcher: ['/((?!_next|favicon.ico).*)'] };

Reading the session

import { iamNext } from '@/lib/iam-next';

export default async function Dashboard() {
  const current = await iamNext.getSession();
  if (!current) return <a href="/login">Sign in</a>;
  return <h1>Welcome, {current.identity.name}</h1>;
}

iamNext.getSession() reads the request's cookies (through headers() and cookies()) and returns { identity, session }. It returns null whenever the server refuses the credential as a sign-in. That covers missing, expired, or revoked sessions, sessions that must step up, unverified email addresses, inactive tenants, and requests from a network the session or tenant does not allow. Any other failure is rethrown. requireSession() returns the session or redirects to the login page with ?next=; Guards covers it with the other wrappers.

• Per-request memoization. The no-argument call goes through React cache, so a layout, its page, and nested server components share one lookup per render. Calls that pass headers explicitly are not memoized. The cache option replaces React's; pass (fn) => fn to disable it.
• After a server action. The helper merges cookies() into the headers it sends. Cookies a server action just set, such as a new session after sign-in, therefore apply to the re-render Next performs in the same response.
• Direct API calls. iamNext.credential() returns { headers } for any iam.api.* call made as the current visitor: iam.api.identities.list(await iamNext.credential(), { tenantId }).
• No cross-request state. The helpers never cache across requests. Memoization is scoped to one render, and there is no module-level session state.

Client components

Client components get the session from the server so their first render needs no fetch. iamNext.sessionForClient() returns the session as plain JSON without the stored token hash, or null. Pass it to IamNextProvider, which is IamProvider plus a router.refresh() whenever the signed-in identity changes in the browser (details).

import type { ReactNode } from 'react';
import { iamNext } from '@/lib/iam-next';
import { Providers } from './providers';

export default async function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers initialSession={await iamNext.sessionForClient()}>{children}</Providers>
      </body>
    </html>
  );
}

Inside the provider, the React hooks (useSession, useAuthorize, useAccessible, useIamClient, Can) work as usual; @better-iam/next/client re-exports them.

Options

createIamNext(iam, options) takes these options. Most applications set loginPath, stepUpPath, and interrupts; headers, cookies, redirect, and the other overrides exist for tests and custom setups.

createIamNext accepts the instance or a factory (() => iam or () => Promise<iam>). Any object with the IamLike surface works; a custom one without endpoint passes baseURL and basePath.

iamNext at a glance

Everything createIamNext returns, and where each member is explained:

In this section

The example app (examples/nextjs) runs all of it on port 3300 with seeded accounts.