[Next.js Tutorial] Server Actions & Mutations: A Practical Guide with Real Examples

In the modern web development world with Next.js, Server Actions and Mutations are a revolution, completely changing how we interact with and mutate server-side data. Forget about verbose API routes and repetitive fetch calls. Now, you can call server-side functions directly from your components, creating a seamless, efficient, and secure programming experience.

This article will help you not only understand "What are Server Actions and Mutations?" but also master how to implement them effectively in your Next.js projects.

1. Server Actions: Extending Your Component's Reach to the Server

Simply put, Server Actions are async functions you define and execute directly on the server, but can be called from both Server Components and Client Components. This opens up a powerful workflow: instead of creating a separate API endpoint just to handle an action (like subscribing an email or adding a product to a cart), you can wrap that logic in a function and call it directly.

To "mark" a function as a Server Action, just add the directive "use server"; at the top of the function or the file containing it.

Basic example with a form:

Imagine you have a simple form for users to add a new todo item.

// app/page.tsx

export default function TodoPage() {
  async function addTodo(formData: FormData) {
    'use server'; // Mark this as a Server Action

    const todo = formData.get('todo');
    // Logic to save 'todo' to the database
    console.log(`Added new todo: ${todo}`);
  }

  return (
    <form action={addTodo}>
      <input type="text" name="todo" />
      <button type="submit">Add Todo</button>
    </form>
  );
}

In this example:

• The addTodo function is defined right inside the component.
• With the "use server"; directive, Next.js knows this function must run on the server.
• The <form>'s action attribute points directly to addTodo. When the form is submitted, Next.js automatically calls this Server Action, passing in a FormData object with the form's data.

The magic here is you don't need to write any fetch code or API routes. Everything happens "magically" but predictably.

2. Mutations: When Actions Change Data

In the context of Server Actions, a Mutation isn't a separate concept or syntax, but rather the purpose of the Server Action: to change data (create, update, or delete—CUD in CRUD). The addTodo function above is a classic mutation.

The real power of mutations with Server Actions is their deep integration with Next.js's caching and revalidation system. After a successful mutation, you usually want the UI to update to reflect the change. Next.js provides utilities like revalidatePath and revalidateTag to handle this elegantly.

Advanced example with Revalidation:

Let's improve the TodoPage example to display a todo list and automatically update after adding a new item.

// app/page.tsx
import { revalidatePath } from 'next/cache';

// Assume this function fetches data from the database
async function getTodos() {
  // ... logic to fetch todos
  return ['Learn Next.js', 'Start a new project'];
}

export default async function TodoPage() {
  const todos = await getTodos();

  async function addTodo(formData: FormData) {
    'use server';

    const todo = formData.get('todo');
    // ... logic to save 'todo' to the database

    // Ask Next.js to revalidate this page's data
    revalidatePath('/');
  }

  return (
    <div>
      <form action={addTodo}>
        <input type="text" name="todo" />
        <button type="submit">Add Todo</button>
      </form>

      <ul>
        {todos.map((todo, index) => (
          <li key={index}>{todo}</li>
        ))}
      </ul>
    </div>
  );
}

When the form is submitted, the addTodo Server Action not only saves the data but also calls revalidatePath('/'). This tells Next.js that the data at / (the homepage) is stale and needs to be fetched again. Next.js will automatically rerun getTodos, re-render TodoPage with the latest data, and send it to the client. The user will see the new todo appear in the list without needing to reload the page.

3. Server Actions vs. API Routes: When to Use Each?

Both Server Actions and API Routes (Route Handlers) let the client communicate with the server. However, they serve different purposes and have their own pros and cons.

Advice:

• Use Server Actions for most data mutation tasks inside your Next.js app. This is the default and recommended choice for its simplicity and tight integration.
• Use API Routes when you need to build a public API with a clear structure for other apps (e.g., mobile apps) or third-party services to consume.

4. Handling State and Errors: Enhancing User Experience

In reality, a mutation doesn't always succeed instantly. You need to handle loading states and possible errors. React hooks like useFormStatus and useFormState are designed for this when working with Server Actions in Client Components.

• useFormStatus: Provides the form's pending state, letting you easily disable the submit button or show a spinner while the action is processing.
• useFormState: Lets your Server Action return a state (e.g., error message, returned data) and update it in the component.

Example with useFormStatus and useFormState:

// app/actions.ts
'use server';

export async function createUser(prevState: any, formData: FormData) {
  const name = formData.get('name');
  if (typeof name !== 'string' || name.length < 3) {
    return { message: 'Name must be at least 3 characters.' };
  }
  // ... logic to create user
  revalidatePath('/');
  return { message: 'User created successfully!' };
}

// app/user-form.tsx
'use client'

import { useFormState, useFormStatus } from 'react-dom'
import { createUser } from './actions'

const initialState = {
  message: '',
}

function SubmitButton() {
  const { pending } = useFormStatus()
  return (
    <button type="submit" aria-disabled={pending}>
      {pending ? 'Creating...' : 'Create User'}
    </button>
  )
}

export function UserForm() {
  const [state, formAction] = useFormState(createUser, initialState)

  return (
    <form action={formAction}>
      <input type="text" name="name" />
      <SubmitButton />
      <p>{state?.message}</p>
    </form>
  )
}

In this example:

• UserForm is a Client Component ('use client').
• useFormState takes the Server Action (createUser) and the initial state, returning the current state and a new action to pass to the form.
• createUser can now return an object with an error or success message.
• SubmitButton uses useFormStatus to automatically update the UI based on the form's pending state.

Conclusion: Server Actions and Mutations—A Shift in Mindset

Server Actions and Mutations are not just a new feature; they represent a shift in how we think about full-stack development with Next.js. By erasing the boundary between client and server, they let us build apps faster, with less code, and more securely.

Mastering this powerful tool will open up new possibilities and help you create smoother, more seamless user experiences. Start integrating them into your projects today!