Form Actions: Replacing API Routes for Mutations

In traditional Next.js applications, form submissions require a client component with an onSubmit handler that calls fetch() to POST data to an API route. This pattern works but requires writing and maintaining both the client-side fetch logic and the server-side route handler separately.

With Server Actions, you replace the fetch call and the API route with a single function. The form element receives the Server Action as its action prop: <form action={serverAction}>. React intercepts the submission and calls the action with the form data automatically.

The Server Action automatically receives a FormData object as its argument when triggered by a form. You access individual fields using formData.get('email') which returns the value as a string. All standard FormData methods are available, including getAll() for multi-select fields.

A Server Action can return a serializable value that the client can use. Returning an error object like { error: 'Email already exists' } or a success flag like { success: true } allows the client to update the UI accordingly without a full page reload.

Because the form action is a Server Action, the page component hosting the form does not need to be a Client Component. The server renders the form as static HTML, and only the interactive parts (like error display) require client-side JavaScript. This reduces the client bundle significantly.

A form with action={serverAction} works without JavaScript enabled. The browser performs a standard HTML form POST, the server executes the action, and the server returns the updated page. This true progressive enhancement means the form degrades gracefully in all environments.

After a Server Action mutates data, cached page data must be refreshed. Calling revalidatePath('/dashboard') inside the action invalidates the Next.js cache for that path, causing the next request to fetch fresh data. This is the standard way to keep server-rendered pages up to date after mutations.

revalidateTag('user-data') provides finer-grained cache invalidation than revalidatePath. You tag fetch calls with next: { tags: ['user-data'] } and then invalidate all tagged data at once from within the Server Action, regardless of which paths display that data.

Server Actions can redirect the user to a new page after a successful mutation by calling redirect('/success') from the next/navigation module. This redirect is handled server-side, which means the browser receives a proper navigation response rather than a client-side redirect.

Server Actions are not limited to form submissions. For button clicks and other non-form triggers, wrap the action call in startTransition(() => action(arg)). This marks the navigation as a transition, allowing React to keep the current UI visible while the action executes on the server.

Server Actions are the right place for server-side validation. Validate the FormData fields, return validation errors if they fail, and only proceed with the mutation if all fields are valid. Libraries like Zod integrate well here: parse the FormData into a typed schema and return the error map on failure.

What does a Server Action receive as its argument when triggered by a form submission?

Server Actions replace the fetch + API route pattern for form mutations. The form action prop accepts a Server Action directly, which receives a FormData object. Actions return serializable results for client UI updates, support revalidatePath and revalidateTag for cache invalidation, and work progressively without JavaScript.