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 Problem With Naive Server Actions
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')returnsstring | null | File— theas stringcast hides a bug waiting to happen - No validation means invalid input reaches your business logic
- Error handling is whatever you add ad hoc to each action
- The return type isn't defined, so the client has no type information
The Foundation — A Result Type
Start 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.
Adding Zod Validation
// 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>;
The Server Action With Full Type Safety
// 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.',
};
}
}
The Client-Side Hook
// 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 };
}
The Form Component
// 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>
);
}
A Reusable Action Wrapper
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 };
}
);
The Payoff
With this pattern in place:
- Every action has a consistent interface —
ActionResult<T> - Validation errors surface to the client with field-level detail
- TypeScript knows the exact shape of success and error responses
- Error handling is centralized rather than ad hoc per action
- Adding a new action means writing the schema and handler — the boilerplate is handled The upfront investment in the wrapper and types pays off quickly across a codebase with more than a handful of Server Actions.
Testing Server Actions
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.
Common Pitfalls
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.