Next.js 16 server actions + Zod with useActionState-shaped results: working versions (tested 2026-10-15)

{
  "name": "nextjs-server-action-zod",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "next": "16.4.1",
    "zod": "4.6.7",
    "react": "19.3.1",
    "react-dom": "19.3.1"
  },
  "devDependencies": {
    "tsx": "4.23.15",
    "@types/node": "24.19.2"
  }
}

"use server";
import { z } from "zod";

const Contact = z.object({
  name: z.string().trim().min(1, "Name is required"),
  email: z.email("Enter a valid email"),
  message: z.string().trim().min(10, "At least 10 characters").max(2000),
  newsletter: z.stringbool().default(false), // checkboxes send "on" or nothing
});

export type ContactState =
  | { ok: true; id: string }
  | { ok: false; errors: Partial<Record<keyof z.infer<typeof Contact>, string[]>>; values?: Record<string, string> };

export const sent: z.infer<typeof Contact>[] = []; // replace with your DB / email call

// Signature matches useActionState(action, initialState): (prevState, formData)
export async function submitContact(_prev: ContactState | null, formData: FormData): Promise<ContactState> {
  const raw = Object.fromEntries(formData) as Record<string, string>;
  const parsed = Contact.safeParse(raw);
  if (!parsed.success) return { ok: false, errors: z.flattenError(parsed.error).fieldErrors, values: raw };
  sent.push(parsed.data);
  return { ok: true, id: `msg_${sent.length}` };
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { submitContact, sent } from "../app/contact/actions.ts";

const fd = (o: Record<string, string>) => { const f = new FormData(); for (const [k, v] of Object.entries(o)) f.append(k, v); return f; };

test("valid submission", async () => {
  const r = await submitContact(null, fd({ name: " Ada ", email: "ada@example.com", message: "Hello there friend", newsletter: "on" }));
  assert.deepEqual(r, { ok: true, id: "msg_1" });
  assert.equal(sent[0].name, "Ada");
  assert.equal(sent[0].newsletter, true);
});

test("returns field errors and echoes values for the form", async () => {
  const r = await submitContact(null, fd({ name: "", email: "nope", message: "short" }));
  assert.equal(r.ok, false);
  if (r.ok) return;
  assert.deepEqual(Object.keys(r.errors).sort(), ["email", "message", "name"]);
  assert.equal(r.values?.email, "nope");
});

test("unchecked checkbox defaults to false", async () => {
  await submitContact(null, fd({ name: "Bo", email: "bo@example.com", message: "Long enough message" }));
  assert.equal(sent.at(-1)!.newsletter, false);
});