React Server Actions Guide

Server Actions enable server-side mutations directly from components. Here's how to use them.

Basic Server Action#

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

export async function createUser(formData: FormData) {
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;

  // Server-side validation
  if (!name || !email) {
    throw new Error('Name and email are required');
  }

  // Database operation
  const user = await db.user.create({
    data: { name, email },
  });

  return user;
}

// app/page.tsx
import { createUser } from './actions';

export default function Page() {
  return (
    <form action={createUser}>
      <input name="name" placeholder="Name" required />
      <input name="email" type="email" placeholder="Email" required />
      <button type="submit">Create User</button>
    </form>
  );
}

With Form Validation#

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

import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

export type ActionState = {
  errors?: {
    name?: string[];
    email?: string[];
    password?: string[];
    _form?: string[];
  };
  success?: boolean;
};

export async function createUser(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  const rawData = {
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  };

  const validationResult = userSchema.safeParse(rawData);

  if (!validationResult.success) {
    return {
      errors: validationResult.error.flatten().fieldErrors,
    };
  }

  try {
    await db.user.create({
      data: validationResult.data,
    });

    return { success: true };
  } catch (error) {
    return {
      errors: {
        _form: ['Failed to create user. Please try again.'],
      },
    };
  }
}

// app/components/UserForm.tsx
'use client';

import { useActionState } from 'react';
import { createUser, ActionState } from '../actions';

export function UserForm() {
  const [state, formAction, isPending] = useActionState<ActionState, FormData>(
    createUser,
    { errors: {} }
  );

  return (
    <form action={formAction}>
      <div>
        <input name="name" placeholder="Name" />
        {state.errors?.name && (
          <span className="error">{state.errors.name[0]}</span>
        )}
      </div>

      <div>
        <input name="email" type="email" placeholder="Email" />
        {state.errors?.email && (
          <span className="error">{state.errors.email[0]}</span>
        )}
      </div>

      <div>
        <input name="password" type="password" placeholder="Password" />
        {state.errors?.password && (
          <span className="error">{state.errors.password[0]}</span>
        )}
      </div>

      {state.errors?._form && (
        <div className="error">{state.errors._form[0]}</div>
      )}

      {state.success && (
        <div className="success">User created successfully!</div>
      )}

      <button type="submit" disabled={isPending}>
        {isPending ? 'Creating...' : 'Create User'}
      </button>
    </form>
  );
}

useFormStatus#

'use client';

import { useFormStatus } from 'react-dom';

function SubmitButton() {
  const { pending, data, method, action } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? 'Submitting...' : 'Submit'}
    </button>
  );
}

function FormFields() {
  const { pending } = useFormStatus();

  return (
    <fieldset disabled={pending}>
      <input name="title" placeholder="Title" />
      <textarea name="content" placeholder="Content" />
    </fieldset>
  );
}

// Usage - SubmitButton must be inside form
export function Form({ action }: { action: (formData: FormData) => Promise<void> }) {
  return (
    <form action={action}>
      <FormFields />
      <SubmitButton />
    </form>
  );
}

Optimistic Updates#

'use client';

import { useOptimistic } from 'react';
import { addTodo, deleteTodo } from './actions';

interface Todo {
  id: string;
  text: string;
  completed: boolean;
  pending?: boolean;
}

export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    (state: Todo[], newTodo: Todo) => [...state, { ...newTodo, pending: true }]
  );

  async function handleSubmit(formData: FormData) {
    const text = formData.get('text') as string;
    const tempId = `temp-${Date.now()}`;

    // Optimistic update
    addOptimisticTodo({
      id: tempId,
      text,
      completed: false,
    });

    // Server action
    await addTodo(formData);
  }

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

      <ul>
        {optimisticTodos.map((todo) => (
          <li
            key={todo.id}
            style={{ opacity: todo.pending ? 0.5 : 1 }}
          >
            {todo.text}
          </li>
        ))}
      </ul>
    </div>
  );
}

Revalidation#

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

import { revalidatePath, revalidateTag } from 'next/cache';

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

  await db.post.create({
    data: { title, content },
  });

  // Revalidate specific path
  revalidatePath('/posts');

  // Or revalidate by tag
  revalidateTag('posts');

  // Revalidate with layout
  revalidatePath('/posts', 'layout');
}

export async function deletePost(id: string) {
  await db.post.delete({ where: { id } });

  // Revalidate the posts list and specific post
  revalidatePath('/posts');
  revalidatePath(`/posts/${id}`);
}

Redirect After Action#

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

import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  const post = await db.post.create({
    data: {
      title: formData.get('title') as string,
      content: formData.get('content') as string,
    },
  });

  // Redirect to the new post
  redirect(`/posts/${post.id}`);
}

export async function logout() {
  await auth.signOut();
  redirect('/login');
}

File Uploads#

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

import { writeFile } from 'fs/promises';
import { join } from 'path';

export async function uploadFile(formData: FormData) {
  const file = formData.get('file') as File;

  if (!file || file.size === 0) {
    return { error: 'No file uploaded' };
  }

  // Validate file type
  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
  if (!allowedTypes.includes(file.type)) {
    return { error: 'Invalid file type' };
  }

  // Validate file size (5MB)
  if (file.size > 5 * 1024 * 1024) {
    return { error: 'File too large' };
  }

  const bytes = await file.arrayBuffer();
  const buffer = Buffer.from(bytes);

  const filename = `${Date.now()}-${file.name}`;
  const path = join(process.cwd(), 'public', 'uploads', filename);

  await writeFile(path, buffer);

  return { success: true, path: `/uploads/${filename}` };
}

// Client component
'use client';

import { useRef, useState } from 'react';
import { uploadFile } from './actions';

export function FileUpload() {
  const [preview, setPreview] = useState<string | null>(null);
  const formRef = useRef<HTMLFormElement>(null);

  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (file) {
      setPreview(URL.createObjectURL(file));
    }
  }

  async function handleSubmit(formData: FormData) {
    const result = await uploadFile(formData);

    if (result.success) {
      formRef.current?.reset();
      setPreview(null);
    }
  }

  return (
    <form ref={formRef} action={handleSubmit}>
      <input
        type="file"
        name="file"
        accept="image/*"
        onChange={handleChange}
      />
      {preview && <img src={preview} alt="Preview" />}
      <button type="submit">Upload</button>
    </form>
  );
}

Error Handling#

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

class ActionError extends Error {
  constructor(
    message: string,
    public code: string
  ) {
    super(message);
    this.name = 'ActionError';
  }
}

export async function riskyAction(formData: FormData) {
  try {
    const result = await db.something.create({
      data: { /* ... */ },
    });
    return { success: true, data: result };
  } catch (error) {
    if (error instanceof PrismaClientKnownRequestError) {
      if (error.code === 'P2002') {
        return { error: 'This item already exists' };
      }
    }
    return { error: 'Something went wrong' };
  }
}

// With error boundary
// app/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Inline Server Actions#

// Define actions inline
export default function Page() {
  async function handleSubmit(formData: FormData) {
    'use server';

    const title = formData.get('title');
    await db.post.create({ data: { title } });
    revalidatePath('/posts');
  }

  return (
    <form action={handleSubmit}>
      <input name="title" />
      <button type="submit">Create</button>
    </form>
  );
}

// With closure over props
export default function DeleteButton({ id }: { id: string }) {
  async function handleDelete() {
    'use server';

    await db.post.delete({ where: { id } });
    revalidatePath('/posts');
  }

  return (
    <form action={handleDelete}>
      <button type="submit">Delete</button>
    </form>
  );
}

Progressive Enhancement#

// Works without JavaScript
export default function ContactForm() {
  async function sendMessage(formData: FormData) {
    'use server';

    await sendEmail({
      to: 'contact@example.com',
      subject: formData.get('subject') as string,
      body: formData.get('message') as string,
    });

    redirect('/thank-you');
  }

  return (
    <form action={sendMessage}>
      <input name="subject" placeholder="Subject" required />
      <textarea name="message" placeholder="Message" required />
      <button type="submit">Send</button>
    </form>
  );
}

Best Practices#

Security:
✓ Always validate input on server
✓ Sanitize user data
✓ Check authentication/authorization
✓ Use CSRF protection (built-in)

Performance:
✓ Keep actions focused
✓ Use revalidation strategically
✓ Consider optimistic updates
✓ Handle loading states

UX:
✓ Show pending states
✓ Provide error feedback
✓ Support progressive enhancement
✓ Handle edge cases

Organization:
✓ Group related actions
✓ Use consistent error handling
✓ Type action returns
✓ Document complex actions

Server Actions simplify data mutations by eliminating API routes. Use them for forms, mutations, and server-side operations. Combine with useActionState for validation, useOptimistic for instant feedback, and always validate inputs on the server.