Build a Zod Validator for Next.js Route Handlers from Excel Data

Per-row schema for an App Router upload handler

Parse the sheet, generate from one row with rootName importRow, then safeParse each row in the handler.

// 1. one row -> JSON sample pasted into the generator
{ "email": "a@x.com", "plan": "pro", "seats": 5 }

// 2. generated (rootName: importRow)
import { z } from "zod";
export const importRow = z.object({
  email: z.string(),
  plan: z.string(),
  seats: z.number().int()
});
export type ImportRow = z.infer<typeof importRow>;

// 3. app/api/import/route.ts (your code)
const rows = XLSX.utils.sheet_to_json(sheet);
for (const row of rows) {
  const r = importRow.safeParse(row);
  if (!r.success) return NextResponse.json(r.error.flatten(), { status: 400 });
}

Add .email() so bad addresses 400 instead of crashing

The generator emits z.string() for the email column. You add .email() to turn a malformed address into a clean 400.

Generated: email: z.string(),

Refined in your handler file:
email: z.string().email(),

Result: importRow.safeParse({ email: "not-an-email", ... })
-> { success: false } -> NextResponse.json(..., { status: 400 })

strictObjects to reject a tampered template

If users must upload your exact template, strict mode turns an extra column into a validation error.

strictObjects: true ->
export const importRow = z.strictObject({
  email: z.string(),
  plan: z.string()
});

Upload with a sneaky extra { email, plan, isAdmin: true }:
importRow.safeParse(row) -> success:false, 'Unrecognized key: isAdmin'
The injected field never reaches your business logic.

Batch-validate the whole upload

Wrap the row schema in z.array() to validate every parsed row in one call inside the handler.

import { importRow } from "./schema";
const rows = XLSX.utils.sheet_to_json(sheet);
const parsed = z.array(importRow).safeParse(rows);
if (!parsed.success) {
  return NextResponse.json(parsed.error.flatten(), { status: 400 });
}
// parsed.data is fully typed as ImportRow[]

Server Action reuse with z.infer

The generated z.infer<> alias removes any duplicate interface in a Server Action.

'use server';
import { importRow, type ImportRow } from "@/lib/import-schema";

export async function importExcel(rows: unknown[]) {
  const clean: ImportRow[] = [];
  for (const row of rows) {
    const r = importRow.safeParse(row);
    if (r.success) clean.push(r.data);
  }
  await db.insert(clean);
}

The redirect target only takes JSON. You still parse the .xlsx in your Next.js handler with SheetJS; the generator is only for producing the schema text from one sample row.

The generator outputs the schema, an import, and a z.infer<> alias — no usage snippets. Choose safeParse for user-facing routes (return 400) and parse only where a throw is acceptable. Earlier drafts of this page wrongly claimed usage comments are generated.

If your sample row had the column populated, it infers z.string() and a later blank row fails safeParse. The generator never adds .optional() — add it yourself, or use the tRPC Router Builder, which makes every field optional after sampling.

A date cell infers z.string(). If your handler expects a Date, change it to z.coerce.date() so safeParse returns a real Date object, otherwise you compare a string.

If the upload pipeline stringifies cells ("5" instead of 5), z.number() rejects it. Either fix the parse step (SheetJS keeps numbers as numbers) or switch to z.coerce.number() in the schema.

Default z.object() strips keys not in the schema, so an unexpected column passes validation and quietly disappears from result.data. Use strictObjects: true (-> z.strictObject()) if a stray column should be a 400.

The generator runs JSON.parse; a partial copy or trailing comma throws and produces nothing. Copy a complete object, or stringify the row in your script (JSON.stringify(rows[0], null, 2)) before pasting.

Array inference reads element zero only. If row one is missing a column, the schema omits it. Paste a fully populated single object instead of the array when building the schema.

JSON to Zod is Pro with a 2 MB free file limit. You only need one row to infer a schema, so trim the sample — never paste the entire workbook's JSON.

The generated schema is plain Zod with no Node APIs, so it runs in the Edge runtime, Node, Deno, and Bun alike. The SheetJS parse step that produces your JSON is the only part with runtime requirements.