How to build a register user flow in Next.js 15 (frontend, backend, database, email)

+-------+        +------------+       +-----------+      +--------+
|Browser|  POST  |  Next.js   | INSERT| Postgres  | SEND |Resend  |
|       |------->|/api/       |------>|  users    |----->|        |
|       |        |auth/       |       |  (verify=F|      |        |
|       |<-------|register    |<------|  id=123)  |<-----|        |
|       |  200   |            |       +-----------+      +--------+
+-------+        +------------+
   |                   |
   | GET /dashboard    | 302 to /check-email
   v                   v
(not signed in yet)    (shows "check your inbox" screen)

+-------+          +------------+       +-----------+
|Email  |  GET     |  Next.js   | UPDATE| Postgres  |
|client |--token-->|/api/       |------>|  users    |
|       |          |auth/verify |       |  verify=T |
|       |<---------|            |<------|           |
|       |  302 to  +------------+       +-----------+
|       |  /login          |
+-------+                   |
                            | set session cookie
                            v
                       (now signed in)

create table users (
  id            bigserial primary key,
  email         citext not null unique,
  password_hash text not null,
  email_verified boolean not null default false,
  created_at    timestamptz not null default now(),
  updated_at    timestamptz not null default now()
);

create table email_verification_tokens (
  id         bigserial primary key,
  user_id    bigint not null references users(id) on delete cascade,
  token_hash text not null unique,
  expires_at timestamptz not null,
  used_at    timestamptz,
  created_at timestamptz not null default now()
);

create index idx_evt_user_unused
  on email_verification_tokens(user_id) where used_at is null;

// app/auth/register/page.tsx
"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";

export default function Register() {
  const router = useRouter();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [pending, setPending] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const rules = {
    minLength: password.length >= 12,
    hasNumber: /[0-9]/.test(password),
    hasLower: /[a-z]/.test(password),
    hasUpper: /[A-Z]/.test(password),
  };
  const valid = Object.values(rules).every(Boolean);

  async function submit(e: React.FormEvent) {
    e.preventDefault();
    setError(null);
    setPending(true);

    const res = await fetch("/api/auth/register", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email, password }),
    });

    setPending(false);

    if (res.status === 429) {
      setError("Too many attempts. Try again in a minute.");
      return;
    }
    if (!res.ok) {
      setError("Something went wrong. Try again.");
      return;
    }
    router.push("/auth/check-email");
  }

  return (
    <form onSubmit={submit} className="max-w-sm mx-auto mt-16 space-y-4">
      <h1 className="text-2xl font-semibold">Create account</h1>

      <label className="block">
        <span className="text-sm">Email</span>
        <input
          type="email"
          required
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="email"
        />
      </label>

      <label className="block">
        <span className="text-sm">Password</span>
        <input
          type="password"
          required
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          className="w-full rounded border p-2 mt-1"
          autoComplete="new-password"
        />
      </label>

      <ul className="text-xs space-y-1">
        <Rule ok={rules.minLength}>At least 12 characters</Rule>
        <Rule ok={rules.hasLower}>A lowercase letter</Rule>
        <Rule ok={rules.hasUpper}>An uppercase letter</Rule>
        <Rule ok={rules.hasNumber}>A number</Rule>
      </ul>

      {error && <p className="text-red-600 text-sm">{error}</p>}

      <button
        type="submit"
        disabled={!valid || pending}
        className="w-full rounded bg-black text-white py-2 disabled:opacity-50"
      >
        {pending ? "Creating..." : "Create account"}
      </button>
    </form>
  );
}

function Rule({ ok, children }: { ok: boolean; children: React.ReactNode }) {
  return (
    <li className={ok ? "text-green-600" : "text-zinc-500"}>
      {ok ? "✓" : "○"} {children}
    </li>
  );
}

// app/api/auth/register/route.ts
import { NextRequest, NextResponse } from "next/server";
import { z } from "zod";
import bcrypt from "bcrypt";
import { randomBytes, createHash } from "crypto";
import { db } from "@/db";
import { users, emailVerificationTokens } from "@/db/schema";
import { eq } from "drizzle-orm";
import { sendVerificationEmail } from "@/lib/email";
import { rateLimit } from "@/lib/rate-limit";

const body = z.object({
  email: z.string().email().max(254),
  password: z
    .string()
    .min(12)
    .max(256)
    .regex(/[a-z]/)
    .regex(/[A-Z]/)
    .regex(/[0-9]/),
});

export async function POST(req: NextRequest) {
  const ip = req.headers.get("x-forwarded-for") ?? "unknown";
  if (await rateLimit(`register:${ip}`, { max: 3, window: 60 })) {
    return NextResponse.json({ ok: true });
  }

  const parsed = body.safeParse(await req.json());
  if (!parsed.success) {
    return NextResponse.json({ ok: true });
  }

  const email = parsed.data.email.toLowerCase().trim();
  const passwordHash = await bcrypt.hash(parsed.data.password, 12);

  const existing = await db.query.users.findFirst({
    where: eq(users.email, email),
  });

  if (existing) {
    return NextResponse.json({ ok: true });
  }

  const [user] = await db
    .insert(users)
    .values({ email, passwordHash, emailVerified: false })
    .returning({ id: users.id });

  const raw = randomBytes(32).toString("base64url");
  const tokenHash = createHash("sha256").update(raw).digest("hex");

  await db.insert(emailVerificationTokens).values({
    userId: user.id,
    tokenHash,
    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
  });

  await sendVerificationEmail(email, raw);

  return NextResponse.json({ ok: true });
}

// lib/email.ts
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY!);
const APP_URL = process.env.APP_URL ?? "https://example.com";

export async function sendVerificationEmail(to: string, rawToken: string) {
  const link = `${APP_URL}/auth/verify?token=${rawToken}`;

  await resend.emails.send({
    from: "hello@example.com",
    to,
    subject: "Confirm your email",
    html: `
      <p>Hi,</p>
      <p>Click the link below to confirm your email and activate your account.</p>
      <p><a href="${link}">Confirm email</a></p>
      <p>This link expires in 24 hours. If you did not create an account, ignore this email.</p>
    `,
    text: `Confirm your email: ${link}\n\nThis link expires in 24 hours. If you did not create an account, ignore this email.`,
  });
}

// app/api/auth/verify/route.ts
import { NextRequest, NextResponse } from "next/server";
import { createHash } from "crypto";
import { db } from "@/db";
import { users, emailVerificationTokens } from "@/db/schema";
import { and, eq, gt, isNull } from "drizzle-orm";

export async function GET(req: NextRequest) {
  const token = req.nextUrl.searchParams.get("token");
  if (!token) {
    return NextResponse.redirect(
      new URL("/auth/verify-failed", req.url),
    );
  }

  const tokenHash = createHash("sha256").update(token).digest("hex");

  const row = await db.query.emailVerificationTokens.findFirst({
    where: and(
      eq(emailVerificationTokens.tokenHash, tokenHash),
      gt(emailVerificationTokens.expiresAt, new Date()),
      isNull(emailVerificationTokens.usedAt),
    ),
  });

  if (!row) {
    return NextResponse.redirect(
      new URL("/auth/verify-failed", req.url),
    );
  }

  await db.transaction(async (tx) => {
    await tx
      .update(users)
      .set({ emailVerified: true })
      .where(eq(users.id, row.userId));
    await tx
      .update(emailVerificationTokens)
      .set({ usedAt: new Date() })
      .where(eq(emailVerificationTokens.id, row.id));
  });

  return NextResponse.redirect(new URL("/auth/login?verified=1", req.url));
}

# Register a new user
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"Correct-Horse-1"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Try to register the same email again. Same 200.
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"Different-Horse-2"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Try a malformed email. Still 200.
$ curl -i -X POST http://localhost:3000/api/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"not-an-email","password":"Correct-Horse-1"}'

HTTP/1.1 200 OK
content-type: application/json

{"ok":true}

# Fire the rate limit.
$ for i in $(seq 1 10); do
    curl -s -X POST http://localhost:3000/api/auth/register \
      -H 'content-type: application/json' \
      -d "{\"email\":\"burst${i}@example.com\",\"password\":\"Correct-Horse-1\"}"
    echo
  done

$ psql $DATABASE_URL -c "select id, email, email_verified from users;"
 id |      email       | email_verified
----+------------------+----------------
  1 | alice@example.com| f

$ psql $DATABASE_URL -c "select user_id, expires_at, used_at from email_verification_tokens;"
 user_id |        expires_at        | used_at
---------+--------------------------+---------
       1 | 2026-04-19 14:30:22+00   | null

$ curl -i "http://localhost:3000/api/auth/verify?token=THE_RAW_TOKEN_FROM_THE_EMAIL"

HTTP/1.1 302 Found
location: /auth/login?verified=1

$ psql $DATABASE_URL -c "select email_verified from users where id = 1;"
 email_verified
----------------
 t

pnpm add kavachos @kavachos/nextjs
pnpm kavachos migrate

// auth.ts
import { kavachos } from "kavachos";
import { nextjsAdapter } from "@kavachos/nextjs";

export const auth = kavachos({
  adapter: nextjsAdapter(),
  database: process.env.DATABASE_URL!,
  providers: {
    password: {
      minLength: 12,
      rules: { uppercase: true, lowercase: true, number: true },
    },
  },
  emailVerification: {
    required: true,
    tokenTTL: "24h",
  },
  email: {
    provider: "resend",
    apiKey: process.env.RESEND_API_KEY!,
    from: "hello@example.com",
  },
});

// app/api/auth/[...kavachos]/route.ts
import { auth } from "@/auth";
export const { GET, POST } = auth.handlers;

// app/auth/register/page.tsx
"use client";
import { useAuth } from "@kavachos/nextjs";

export default function Register() {
  const { register, pending, error } = useAuth();
  return (
    <form action={register}>
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <button disabled={pending}>Create account</button>
      {error && <p>{error.message}</p>}
    </form>
  );
}