\n
\n Server Actions in Next.js App Router look deceptively simple \u2014 write an async function, mark it with ‘use server’, call it from a Client Component. The surface area is small.<\/p>\n
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.<\/p>\n
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.<\/p>\n
The Problem With Naive Server Actions<\/p>\n
The simplest Server Action works fine for prototypes:<\/p>\n
‘use server’;<\/p>\n
export async function submitForm(formData: FormData) {
\n const prompt = formData.get(‘prompt’) as string;
\n \/\/ No validation, no type safety, any error handling is ad hoc
\n const result = await generateImage(prompt);
\n return result;
\n}<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The issues:<\/p>\n
formData.get(‘prompt’) returns string | null | File \u2014 the as string cast hides a bug waiting to happen
\nNo validation means invalid input reaches your business logic
\nError handling is whatever you add ad hoc to each action<\/p>\n
– The return type isn’t defined, so the client has no type information<\/p>\n
The Foundation \u2014 A Result Type<\/p>\n
Start with a discriminated union for action results:<\/p>\n
\/\/ lib\/types\/action.ts
\nexport type ActionSuccessT> = {
\n success: true;
\n data: T;
\n};<\/p>\n
export type ActionError = {
\n success: false;
\n error: string;
\n fieldErrors?: Recordstring, string()>;
\n};<\/p>\n
export type ActionResultT> = ActionSuccessT> | ActionError;<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
Every Server Action returns Promise>. The client always knows whether the action succeeded and what shape the data has.<\/p>\n
Adding Zod Validation<\/p>\n
\/\/ lib\/schemas\/generate.ts
\nimport { z } from ‘zod’;<\/p>\n
export const GenerateSchema = z.object({
\n prompt: z
\n .string()
\n .min(3, ‘Prompt must be at least 3 characters’)
\n .max(500, ‘Prompt must be under 500 characters’)
\n .trim(),
\n aspectRatio: z.enum((‘1:1′, ’16:9’, ‘9:16’, ‘4:5’)).default(‘1:1’),
\n style: z.string().optional(),
\n});<\/p>\n
export type GenerateInput = z.infertypeof GenerateSchema>;<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The Server Action With Full Type Safety<\/p>\n
\/\/ app\/actions\/generate.ts
\n‘use server’;<\/p>\n
import { z } from ‘zod’;
\nimport { GenerateSchema, GenerateInput } from ‘@\/lib\/schemas\/generate’;
\nimport { ActionResult } from ‘@\/lib\/types\/action’;<\/p>\n
type GenerateResult = {
\n jobId: string;
\n estimatedSeconds: number;
\n};<\/p>\n
export async function generateImageAction(
\n input: GenerateInput
\n): PromiseActionResultGenerateResult>> {
\n \/\/ Validate \u2014 even though TypeScript already knows the type,
\n \/\/ runtime validation catches anything that slips through
\n const parsed = GenerateSchema.safeParse(input);<\/p>\n
if (!parsed.success) {
\n return {
\n success: false,
\n error: ‘Invalid input’,
\n fieldErrors: parsed.error.flatten().fieldErrors as Recordstring, string()>,
\n };
\n }<\/p>\n
try {
\n const { prompt, aspectRatio, style } = parsed.data;<\/p>\n
\/\/ Your business logic here
\n const job = await submitGenerationJob({ prompt, aspectRatio, style });<\/p>\n
return {
\n success: true,
\n data: {
\n jobId: job.id,
\n estimatedSeconds: job.estimatedDuration,
\n },
\n };
\n } catch (error) {
\n \/\/ Log server-side for debugging
\n console.error(‘Generation failed:’, error);<\/p>\n
\/\/ Return user-friendly error to client
\n return {
\n success: false,
\n error: ‘Generation failed. Please try again.’,
\n };
\n }
\n}<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The Client-Side Hook<\/p>\n
\/\/ hooks\/useGenerate.ts
\n‘use client’;<\/p>\n
import { useState, useTransition } from ‘react’;
\nimport { generateImageAction } from ‘@\/app\/actions\/generate’;
\nimport { GenerateInput } from ‘@\/lib\/schemas\/generate’;<\/p>\n
export function useGenerate() {
\n const (isPending, startTransition) = useTransition();
\n const (result, setResult) = useState{ jobId: string } | null>(null);
\n const (error, setError) = useStatestring | null>(null);<\/p>\n
const generate = (input: GenerateInput) => {
\n setError(null);
\n setResult(null);<\/p>\n
startTransition(async () => {
\n const response = await generateImageAction(input);<\/p>\n
if (response.success) {
\n setResult({ jobId: response.data.jobId });
\n } else {
\n setError(response.error);
\n }
\n });
\n };<\/p>\n
return { generate, isPending, result, error };
\n}<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The Form Component<\/p>\n
\/\/ components\/GenerateForm.tsx
\n‘use client’;<\/p>\n
import { useForm } from ‘react-hook-form’;
\nimport { zodResolver } from ‘@hookform\/resolvers\/zod’;
\nimport { GenerateSchema, GenerateInput } from ‘@\/lib\/schemas\/generate’;
\nimport { useGenerate } from ‘@\/hooks\/useGenerate’;<\/p>\n
export function GenerateForm() {
\n const { generate, isPending, error } = useGenerate();<\/p>\n
const { register, handleSubmit, formState: { errors } } = useFormGenerateInput>({
\n resolver: zodResolver(GenerateSchema),
\n defaultValues: {
\n aspectRatio: ‘1:1’,
\n },
\n });<\/p>\n
return (
\n form onSubmit={handleSubmit(generate)} className=”flex flex-col gap-4″>
\n div>
\n textarea
\n {…register(‘prompt’)}
\n placeholder=”Describe what you want to generate…”
\n className=”w-full p-3 rounded-xl border border-border bg-card
\n text-foreground resize-none h-24 focus:outline-none
\n focus:ring-2 focus:ring-orange-500″
\n \/>
\n {errors.prompt && (
\n p className=”text-sm text-red-500 mt-1″>{errors.prompt.message}p>
\n )}
\n div><\/p>\n
select
\n {…register(‘aspectRatio’)}
\n className=”p-2 rounded-lg border border-border bg-card text-foreground”
\n >
\n option value=”1:1″>Square (1:1)option>
\n option value=”16:9″>Landscape (16:9)option>
\n option value=”9:16″>Portrait (9:16)option>
\n option value=”4:5″>Instagram (4:5)option>
\n select><\/p>\n
{error && (
\n p className=”text-sm text-red-500″>{error}p>
\n )}<\/p>\n
button
\n type=”submit”
\n disabled={isPending}
\n className=”px-6 py-3 bg-orange-500 text-white rounded-full
\n font-medium hover:bg-orange-600 transition-colors
\n disabled:opacity-50 disabled:cursor-not-allowed”
\n >
\n {isPending ? ‘Generating…’ : ‘Generate’}
\n button>
\n form>
\n );
\n}<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
A Reusable Action Wrapper<\/p>\n
For larger applications with many actions, a wrapper reduces boilerplate:<\/p>\n
\/\/ lib\/action-wrapper.ts
\nimport { z } from ‘zod’;
\nimport { ActionResult } from ‘.\/types\/action’;<\/p>\n
export function createActionTInput, TOutput>(
\n schema: z.ZodSchemaTInput>,
\n handler: (input: TInput) => PromiseTOutput>
\n) {
\n return async (input: unknown): PromiseActionResultTOutput>> => {
\n const parsed = schema.safeParse(input);<\/p>\n
if (!parsed.success) {
\n return {
\n success: false,
\n error: ‘Validation failed’,
\n fieldErrors: parsed.error.flatten().fieldErrors as Recordstring, string()>,
\n };
\n }<\/p>\n
try {
\n const data = await handler(parsed.data);
\n return { success: true, data };
\n } catch (error) {
\n console.error(‘Action error:’, error);
\n return {
\n success: false,
\n error: error instanceof Error ? error.message : ‘Something went wrong’
\n };
\n }
\n };
\n}<\/p>\n
\/\/ Usage
\nexport const generateImageAction = createAction(
\n GenerateSchema,
\n async (input) => {
\n const job = await submitGenerationJob(input);
\n return { jobId: job.id };
\n }
\n);<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
The Payoff<\/p>\n
With this pattern in place:<\/p>\n
Every action has a consistent interface \u2014 ActionResult<\/p>\n
Validation errors surface to the client with field-level detail
\nTypeScript knows the exact shape of success and error responses
\nError handling is centralized rather than ad hoc per action
\nAdding a new action means writing the schema and handler \u2014 the boilerplate is handled
\nThe upfront investment in the wrapper and types pays off quickly across a codebase with more than a handful of Server Actions.<\/p>\n
Testing Server Actions<\/p>\n
Server Actions are async functions \u2014 they’re straightforward to unit test:<\/p>\n
\/\/ __tests__\/actions\/generate.test.ts
\nimport { generateImageAction } from ‘@\/app\/actions\/generate’;<\/p>\n
\/\/ Mock the generation service
\njest.mock(‘@\/lib\/generation’, () => ({
\n submitGenerationJob: jest.fn(),
\n}));<\/p>\n
import { submitGenerationJob } from ‘@\/lib\/generation’;
\nconst mockSubmit = submitGenerationJob as jest.Mock;<\/p>\n
describe(‘generateImageAction’, () => {
\n it(‘returns success with valid input’, async () => {
\n mockSubmit.mockResolvedValue({ id: ‘job-123’, estimatedDuration: 8 });<\/p>\n
const result = await generateImageAction({
\n prompt: ‘A sunset over mountains’,
\n aspectRatio: ’16:9′,
\n });<\/p>\n
expect(result.success).toBe(true);
\n if (result.success) {
\n expect(result.data.jobId).toBe(‘job-123’);
\n }
\n });<\/p>\n
it(‘returns validation error for short prompt’, async () => {
\n const result = await generateImageAction({
\n prompt: ‘hi’, \/\/ Too short
\n aspectRatio: ‘1:1’,
\n });<\/p>\n
expect(result.success).toBe(false);
\n if (!result.success) {
\n expect(result.fieldErrors?.prompt).toBeDefined();
\n }
\n });<\/p>\n
it(‘returns error when service throws’, async () => {
\n mockSubmit.mockRejectedValue(new Error(‘Service unavailable’));<\/p>\n
const result = await generateImageAction({
\n prompt: ‘A valid prompt that is long enough’,
\n aspectRatio: ‘1:1’,
\n });<\/p>\n
expect(result.success).toBe(false);
\n });
\n});<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
Testing with the ActionResult type makes assertions clean \u2014 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.<\/p>\n
Common Pitfalls<\/p>\n
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.<\/p>\n
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:<\/p>\n
import { revalidatePath } from ‘next\/cache’;<\/p>\n
export async function deleteItem(id: string): PromiseActionResultvoid>> {
\n try {
\n await db.items.delete(id);
\n revalidatePath(‘\/items’); \/\/ Update the cache
\n return { success: true, data: undefined };
\n } catch {
\n return { success: false, error: ‘Failed to delete item’ };
\n }
\n}<\/p>\n
Enter fullscreen mode<\/p>\n
Exit fullscreen mode<\/p>\n
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.<\/p>\n