Building a Type-Safe API Layer in Next.js App Router With Zod and Server Actions

A developer at pixova.io built a type-safe API layer for Next.js App Router using Zod validation and discriminated union types for Server Actions. The pattern ensures runtime validation, consistent error handling, and type safety across the client-server boundary, as demonstrated in the generation pipeline for the company's free AI wallpaper maker.

Server Actions in Next.js App Router look deceptively simple — write an async function, mark it with 'use server' , call it from a Client Component. The surface area is small. The problems surface when you start thinking about validation, error handling, and type safety across the client-server boundary. Without a deliberate approach, you end up with untyped form data on the server, error handling that varies across actions, and client code that can't trust the shape of what comes back. Here's the pattern I landed on for type-safe Server Actions with Zod validation and consistent error handling, from building the generation pipeline powering the free AI wallpaper maker https://pixova.io/blog/ai-wallpaper-maker-free at pixova.io. The simplest Server Action works fine for prototypes: js 'use server'; export async function submitForm formData: FormData { const prompt = formData.get 'prompt' as string; // No validation, no type safety, any error handling is ad hoc const result = await generateImage prompt ; return result; } The issues: formData.get 'prompt' returns string | null | File — the as string cast hides a bug waiting to happenStart with a discriminated union for action results: // lib/types/action.ts export type ActionSuccess<T = { success: true; data: T; }; export type ActionError = { success: false; error: string; fieldErrors?: Record<string, string ; }; export type ActionResult<T = ActionSuccess<T | ActionError; Every Server Action returns Promise<ActionResult<T . The client always knows whether the action succeeded and what shape the data has. js // lib/schemas/generate.ts import { z } from 'zod'; export const GenerateSchema = z.object { prompt: z .string .min 3, 'Prompt must be at least 3 characters' .max 500, 'Prompt must be under 500 characters' .trim , aspectRatio: z.enum '1:1', '16:9', '9:16', '4:5' .default '1:1' , style: z.string .optional , } ; export type GenerateInput = z.infer<typeof GenerateSchema ; js // app/actions/generate.ts 'use server'; import { z } from 'zod'; import { GenerateSchema, GenerateInput } from '@/lib/schemas/generate'; import { ActionResult } from '@/lib/types/action'; type GenerateResult = { jobId: string; estimatedSeconds: number; }; export async function generateImageAction input: GenerateInput : Promise<ActionResult<GenerateResult { // Validate — even though TypeScript already knows the type, // runtime validation catches anything that slips through const parsed = GenerateSchema.safeParse input ; if parsed.success { return { success: false, error: 'Invalid input', fieldErrors: parsed.error.flatten .fieldErrors as Record<string, string , }; } try { const { prompt, aspectRatio, style } = parsed.data; // Your business logic here const job = await submitGenerationJob { prompt, aspectRatio, style } ; return { success: true, data: { jobId: job.id, estimatedSeconds: job.estimatedDuration, }, }; } catch error { // Log server-side for debugging console.error 'Generation failed:', error ; // Return user-friendly error to client return { success: false, error: 'Generation failed. Please try again.', }; } } js // hooks/useGenerate.ts 'use client'; import { useState, useTransition } from 'react'; import { generateImageAction } from '@/app/actions/generate'; import { GenerateInput } from '@/lib/schemas/generate'; export function useGenerate { const isPending, startTransition = useTransition ; const result, setResult = useState<{ jobId: string } | null null ; const error, setError = useState<string | null null ; const generate = input: GenerateInput = { setError null ; setResult null ; startTransition async = { const response = await generateImageAction input ; if response.success { setResult { jobId: response.data.jobId } ; } else { setError response.error ; } } ; }; return { generate, isPending, result, error }; } js // components/GenerateForm.tsx 'use client'; import { useForm } from 'react-hook-form'; import { zodResolver } from '@hookform/resolvers/zod'; import { GenerateSchema, GenerateInput } from '@/lib/schemas/generate'; import { useGenerate } from '@/hooks/useGenerate'; export function GenerateForm { const { generate, isPending, error } = useGenerate ; const { register, handleSubmit, formState: { errors } } = useForm<GenerateInput { resolver: zodResolver GenerateSchema , defaultValues: { aspectRatio: '1:1', }, } ; return <form onSubmit={handleSubmit generate } className="flex flex-col gap-4" <div <textarea {...register 'prompt' } placeholder="Describe what you want to generate..." className="w-full p-3 rounded-xl border border-border bg-card text-foreground resize-none h-24 focus:outline-none focus:ring-2 focus:ring-orange-500" / {errors.prompt && <p className="text-sm text-red-500 mt-1" {errors.prompt.message}</p } </div <select {...register 'aspectRatio' } className="p-2 rounded-lg border border-border bg-card text-foreground" <option value="1:1" Square 1:1 </option <option value="16:9" Landscape 16:9 </option <option value="9:16" Portrait 9:16 </option <option value="4:5" Instagram 4:5 </option </select {error && <p className="text-sm text-red-500" {error}</p } <button type="submit" disabled={isPending} className="px-6 py-3 bg-orange-500 text-white rounded-full font-medium hover:bg-orange-600 transition-colors disabled:opacity-50 disabled:cursor-not-allowed" {isPending ? 'Generating...' : 'Generate'} </button </form ; } For larger applications with many actions, a wrapper reduces boilerplate: js // lib/action-wrapper.ts import { z } from 'zod'; import { ActionResult } from './types/action'; export function createAction<TInput, TOutput schema: z.ZodSchema<TInput , handler: input: TInput = Promise<TOutput { return async input: unknown : Promise<ActionResult<TOutput = { const parsed = schema.safeParse input ; if parsed.success { return { success: false, error: 'Validation failed', fieldErrors: parsed.error.flatten .fieldErrors as Record<string, string , }; } try { const data = await handler parsed.data ; return { success: true, data }; } catch error { console.error 'Action error:', error ; return { success: false, error: error instanceof Error ? error.message : 'Something went wrong' }; } }; } // Usage export const generateImageAction = createAction GenerateSchema, async input = { const job = await submitGenerationJob input ; return { jobId: job.id }; } ; With this pattern in place: ActionResult<T Server Actions are async functions — they're straightforward to unit test: js // tests /actions/generate.test.ts import { generateImageAction } from '@/app/actions/generate'; // Mock the generation service jest.mock '@/lib/generation', = { submitGenerationJob: jest.fn , } ; import { submitGenerationJob } from '@/lib/generation'; const mockSubmit = submitGenerationJob as jest.Mock; describe 'generateImageAction', = { it 'returns success with valid input', async = { mockSubmit.mockResolvedValue { id: 'job-123', estimatedDuration: 8 } ; const result = await generateImageAction { prompt: 'A sunset over mountains', aspectRatio: '16:9', } ; expect result.success .toBe true ; if result.success { expect result.data.jobId .toBe 'job-123' ; } } ; it 'returns validation error for short prompt', async = { const result = await generateImageAction { prompt: 'hi', // Too short aspectRatio: '1:1', } ; expect result.success .toBe false ; if result.success { expect result.fieldErrors?.prompt .toBeDefined ; } } ; it 'returns error when service throws', async = { mockSubmit.mockRejectedValue new Error 'Service unavailable' ; const result = await generateImageAction { prompt: 'A valid prompt that is long enough', aspectRatio: '1:1', } ; expect result.success .toBe false ; } ; } ; Testing with the ActionResult type makes assertions clean — the discriminated union means TypeScript narrows the type inside the if result.success block, so you get full type checking on both success and error paths. Forgetting that Server Actions run on the server. They don't have access to window , document , or browser APIs. If you're calling a Server Action from a component that also uses browser APIs, make sure the action itself doesn't try to use them. Not handling revalidatePath or revalidateTag after mutations. If an action mutates data and the page should reflect that, you need to explicitly invalidate the cache: js import { revalidatePath } from 'next/cache'; export async function deleteItem id: string : Promise<ActionResult<void { try { await db.items.delete id ; revalidatePath '/items' ; // Update the cache return { success: true, data: undefined }; } catch { return { success: false, error: 'Failed to delete item' }; } } Passing complex objects when primitives work. Server Actions serialize arguments across the network. Simple types strings, numbers, plain objects serialize cleanly. Class instances, functions, and non-serializable objects don't. Keep action inputs to JSON-serializable types.