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

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 at pixova.io.

The simplest Server Action works fine for prototypes:

'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.

// 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:

// 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:

// __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:

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.