Next.js Server Actions: Complete Guide to Full-Stack Mutations in 2026

What Are Server Actions?#

Server Actions are asynchronous functions that run exclusively on the server and can be called directly from React components — both Server and Client Components. They eliminate the need to create dedicated API route files for mutations (form submissions, data updates, deletions) by allowing you to define server-side logic directly alongside the components that use it.

This is a significant architectural simplification: instead of writing a React form → fetch to /api/submit → API route handler → database, you write a React form that calls an async function defined in your component file. The function runs on the server, with direct database access, but is invoked from the client.

How Server Actions Work Internally#

When Next.js encounters a function marked with 'use server', it creates a server endpoint for that function and generates a client-side stub that serializes arguments, sends them to the server endpoint, and returns the deserialized result.

The security implications are important: Server Actions are real HTTP endpoints. Never trust the arguments received in a Server Action without validation — a malicious user can call any Server Action directly. Always validate inputs with Zod or similar before processing.

Defining Server Actions#

Server Actions can be defined in two ways:

Inline in a Server Component: Add 'use server' directive to an async function inside a Server Component. The function has access to the server's environment (database connections, secrets) and runs entirely on the server.

In a dedicated actions file: Create a file with 'use server' at the top level. All exports from this file become Server Actions accessible from any component. This is the recommended pattern for reusable actions.

Form Handling and Progressive Enhancement#

Server Actions integrate naturally with HTML forms. Set the form's action attribute to a Server Action, and the form will work even if JavaScript fails to load — a key principle of progressive enhancement.

With JavaScript enabled, Next.js intercepts form submissions and calls the Server Action without a full page reload, providing a SPA-like experience while maintaining server-side processing.

For complex forms with validation feedback, use the useActionState hook (previously useFormState) to capture the return value of the Server Action and display validation errors inline.

Optimistic Updates with useOptimistic#

For responsive UIs, update the interface immediately when a user performs an action, before the server has confirmed success. The useOptimistic hook manages this pattern:

1. Define the optimistic state and reducer
2. Call addOptimistic when the user triggers an action
3. The UI updates immediately with the optimistic state
4. The Server Action runs in the background
5. On completion, the real server data replaces the optimistic state
6. On error, the optimistic state is rolled back

This pattern is essential for like/unlike actions, toggles, and any UI where immediate feedback matters.

Security Considerations#

Server Actions have a different security surface than traditional API routes:

• Authentication: Check authentication at the top of every Server Action. Never assume a Server Action is called only from your own UI.
• Authorization: Verify the calling user has permission to perform the specific action on the specific resource.
• Input validation: Validate and sanitize all inputs with Zod schemas before processing.
• CSRF protection: Next.js Server Actions include automatic CSRF protection via origin checking. Do not disable this.

When NOT to Use Server Actions#

• Large file uploads: Use pre-signed URLs to upload directly to object storage (S3, Cloudflare R2) without routing binary data through your Next.js server
• Webhooks and external callbacks: Use API routes, which provide more control over HTTP response status codes and headers
• Server-Sent Events (SSE): Use API routes with a readable stream for real-time event streaming