Introduction to Server Actions ('use server')

Introduction to Server Actions ('use server')

Server Actions are asynchronous functions that execute on the server. They allow handling form submissions, data mutations, and backend logic directly from React components without building dedicated API endpoints.

Defining Server Actions

You can declare Server Actions in two places:

1. Inside a dedicated file: Add 'use server'; at the top of the module file. All exported functions become Server Actions.
2. Inline inside a Server Component: Add 'use server'; at the top of the function body.

Dedicated Action File (Recommended):

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

import db from '@/lib/db';
import { revalidatePath } from 'next/cache';

export async function createTodo(formData: FormData) {
  const title = formData.get('title') as string;

  if (!title) {
    throw new Error('Title is required');
  }

  await db.todo.create({ data: { title, completed: false } });

  // Revalidate cache for the homepage!
  revalidatePath('/');
}

Invoking from a Form (Progressive Enhancement):

// app/page.tsx - Server Component
import { createTodo } from '@/app/actions';

export default function TodoPage() {
  return (
    <main className="p-6">
      <form action={createTodo} className="flex gap-2">
        <input
          type="text"
          name="title"
          placeholder="New Todo..."
          className="border p-2 rounded"
          required
        />
        <button type="submit" className="bg-blue-600 text-white px-4 py-2 rounded">
          Add Todo
        </button>
      </form>
    </main>
  );
}

Why Server Actions are Powerful

• Progressive Enhancement: Forms submitted using Server Actions work even before JavaScript finishes loading on the client!
• Zero API Boilerplate: Eliminates the need to construct manual POST endpoints in route.ts.
• Automatic Security: Next.js automatically secures Server Actions with POST-only requests, CORS headers, and encrypted action IDs.

Server Actions vs Traditional API Routes

TL;DR

• Server Actions are marked with the 'use server' directive.
• Pass Server Actions to the action prop of standard HTML <form> elements.
• Server Actions support Progressive Enhancement out of the box.
• Call revalidatePath() inside Server Actions to refresh the user interface automatically.