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;
}
Enter fullscreen mode
Exit fullscreen mode
The issues:
formData.get(‘prompt’) returns string | null | File — the as string cast 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 ActionSuccessT> = {
success: true;
data: T;
};
export type ActionError = {
success: false;
error: string;
fieldErrors?: Recordstring, string()>;
};
export type ActionResultT> = ActionSuccessT> | ActionError;
Enter fullscreen mode
Exit fullscreen mode
Every Server Action returns Promise>. 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.infertypeof GenerateSchema>;
Enter fullscreen mode
Exit fullscreen mode
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
): PromiseActionResultGenerateResult>> {
// 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 Recordstring, 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.’,
};
}
}
Enter fullscreen mode
Exit fullscreen mode
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) = useStatestring | 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 };
}
Enter fullscreen mode
Exit fullscreen mode
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 } } = useFormGenerateInput>({
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>
);
}
Enter fullscreen mode
Exit fullscreen mode
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 createActionTInput, TOutput>(
schema: z.ZodSchemaTInput>,
handler: (input: TInput) => PromiseTOutput>
) {
return async (input: unknown): PromiseActionResultTOutput>> => {
const parsed = schema.safeParse(input);
if (!parsed.success) {
return {
success: false,
error: ‘Validation failed’,
fieldErrors: parsed.error.flatten().fieldErrors as Recordstring, 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 };
}
);
Enter fullscreen mode
Exit fullscreen mode
The Payoff
With this pattern in place:
Every action has a consistent interface — ActionResult
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);
});
});
Enter fullscreen mode
Exit fullscreen mode
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): PromiseActionResultvoid>> {
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’ };
}
}
Enter fullscreen mode
Exit fullscreen mode
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.
