Next.js Server Actions for Form Handling

This is part of the AI Automation Engineer Roadmap series.

TL;DR

Use Server Actions with useActionState to handle form submissions directly on the server with validation, error handling, and progressive enhancement built in.

Why This Matters

Handling forms in Next.js traditionally requires creating API routes, writing fetch calls, managing loading state, and handling errors manually. For simple mutations like creating a post or updating a profile, this boilerplate adds up. Worse, forms break entirely when JavaScript fails to load.

Server Actions matter because forms are one of the most common mutation flows in an app:

• ›contact forms
• ›account updates
• ›checkout steps
• ›newsletter signups
• ›dashboard CRUD operations

If your form architecture is noisy, every one of those flows becomes harder to build and maintain. Server Actions simplify the mutation path by letting the form post directly to a server function instead of bouncing through a hand-written API route.

How the Model Changes

The key shift is that the form submits to a server function, not to a client-side fetch handler.

That gives you a cleaner flow:

1. ›the browser submits native form data
2. ›Next.js invokes the Server Action on the server
3. ›the action validates and performs the mutation
4. ›the result returns into useActionState
5. ›the UI renders success or error state

This is simpler than:

• ›creating a route handler
• ›wiring client fetch logic
• ›handling pending state separately
• ›duplicating validation between client and server

Define the Server Action

// app/actions.ts
"use server";
 
import { z } from "zod";
 
const ContactSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  message: z.string().min(10),
});
 
export async function submitContact(prevState: any, formData: FormData) {
  const raw = Object.fromEntries(formData);
  const result = ContactSchema.safeParse(raw);
 
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
      message: null,
    };
  }
 
  await db.contact.create({ data: result.data });
 
  return { errors: null, message: "Message sent successfully!" };
}

Build the Form Component

"use client";
 
import { useActionState } from "react";
import { submitContact } from "./actions";
 
export function ContactForm() {
  const [state, formAction, isPending] = useActionState(submitContact, {
    errors: null,
    message: null,
  });
 
  return (
    <form action={formAction}>
      <input name="name" placeholder="Your name" />
      {state.errors?.name && <p className="text-red-500">{state.errors.name}</p>}
 
      <input name="email" type="email" placeholder="Email" />
      {state.errors?.email && <p className="text-red-500">{state.errors.email}</p>}
 
      <textarea name="message" placeholder="Message" />
      {state.errors?.message && <p className="text-red-500">{state.errors.message}</p>}
 
      <button type="submit" disabled={isPending}>
        {isPending ? "Sending..." : "Send Message"}
      </button>
 
      {state.message && <p className="text-green-500">{state.message}</p>}
    </form>
  );
}

No API route, no fetch call, no manual state management.

What a Good Form Action Should Return

The return shape from your action becomes part of your UI contract. Keep it predictable.

A practical pattern is:

type ActionState = {
  errors: Record<string, string[]> | null;
  message: string | null;
};

That makes it easy to display:

• ›field-level errors
• ›form-level messages
• ›pending states from useActionState

If your return shape changes arbitrarily between forms, the UI layer gets messy fast.

Validation Patterns That Work Well

Parse FormData on the Server

Validation should happen at the trust boundary, which is the Server Action itself.

const raw = Object.fromEntries(formData);
const result = ContactSchema.safeParse(raw);

This matters even if you also validate on the client. Client-side validation improves UX. Server-side validation protects the mutation.

Keep the Schema Close to the Action

For small forms, keep the Zod schema near the action. For larger apps, extract it into a shared validation module so your server action, route handlers, and tests all use the same schema.

Normalize Input Deliberately

Form values arrive as strings. That means checkboxes, numbers, and dates usually need explicit parsing or coercion. A lot of subtle bugs come from skipping this step.

Progressive Enhancement Is a Real Advantage

One of the strongest reasons to use Server Actions for forms is that they preserve native form behavior.

When the form uses the action prop:

• ›it can submit without custom JavaScript fetch logic
• ›it degrades more gracefully if client JS fails
• ›it aligns with normal browser behavior

That is not just a progressive enhancement talking point. It reduces the number of moving parts in a critical user flow.

Handling Redirects and Revalidation

Many forms do not just return a message. They create or update data, then need to refresh cached views or redirect.

Common server-side follow-ups:

• ›revalidatePath() after mutations
• ›redirect() after successful submissions
• ›cache tag invalidation for dashboard data

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
 
export async function createPost(prevState: any, formData: FormData) {
  const raw = Object.fromEntries(formData);
  const result = PostSchema.safeParse(raw);
 
  if (!result.success) {
    return {
      errors: result.error.flatten().fieldErrors,
      message: null,
    };
  }
 
  const post = await db.post.create({ data: result.data });
 
  revalidatePath("/dashboard/posts");
  redirect(`/dashboard/posts/${post.id}`);
}

This is one of the biggest ergonomic wins over the older API-route-plus-fetch pattern.

Authentication and Authorization Still Matter

Server Actions do not automatically make a mutation safe. You still need to verify:

• ›who is submitting the form
• ›whether they are allowed to perform the action
• ›whether the target resource belongs to them

That logic belongs in the action or in the service layer the action calls.

Common Mistakes

Treating Server Actions as a Shortcut Around Validation

The server function is exactly where validation should happen. Skipping it just because the form "already validated in the browser" is a bad trade.

Returning Inconsistent Error Shapes

If one action returns strings, another returns nested objects, and a third throws raw errors, your form components become harder to reuse.

Mixing Too Much Business Logic into the UI Component

The client form component should mostly render fields and state. Validation, persistence, permissions, and side effects belong on the server.

Forgetting No-JS Behavior

If your form only works because of extra client logic layered on top, you are giving up one of the best parts of Server Actions.

Production Recommendations

If you are using Server Actions for real app forms, a good baseline is:

1. ›validate with Zod in the action
2. ›return a consistent action state shape
3. ›use useActionState for field and form messages
4. ›revalidate or redirect after successful writes
5. ›keep authorization checks on the server

That pattern works well for most App Router forms without falling back to an API route for every mutation.

Why This Works

Server Actions are async functions that execute on the server when the form is submitted. The action prop on <form> uses native HTML form submission, so the form works even without JavaScript (progressive enhancement). useActionState manages the form state lifecycle, providing the previous return value and a pending flag. Zod validation runs server-side, ensuring no invalid data reaches your database regardless of client-side manipulation.

Final Takeaway

Server Actions are the right default for many Next.js form mutations. They reduce boilerplate, preserve progressive enhancement, and keep validation at the trust boundary. Use them when you want a cleaner server-first form flow, not just a different syntax for the same old pattern.