re:re:actable
Урок 013 минуты чтения

Server Actions: что это и какую проблему решают

На этой странице
Кратко

Server Action — асинхронная серверная функция, которую интерфейс может вызвать для изменения данных: отправки формы, сохранения настройки. Actions сокращают код, связывающий форму приложения с серверной операцией, но оставляют разработчику саму операцию и ее проверки.

Вопрос

Что такое Server Actions, как связать серверную операцию с формой и почему иногда это удобнее отдельного API-маршрута?

Основная идея

При работе через API разработчик создает HTTP-обработчик POST, пишет запрос из браузера, разбирает тело на сервере и обновляет интерфейс. Это полезно для универсального HTTP API, но создает лишний код для простой внутренней формы. Server Action позволяет передать серверную функцию в action формы — передачу данных и сетевой вызов организуют React и Next.js.

Через API:    форма -> клиентский fetch -> HTTP-обработчик -> изменение
Через Action: форма -> запрос, организованный Next.js -> серверная функция

Это не локальный вызов в браузере: при клиентском обращении Next.js отправляет POST-запрос. Тело функции выполняется на сервере, поэтому там можно обращаться к базе данных и приватным настройкам. Action не устраняет задержку сети и не делает запрос автоматически доверенным.

Пример: Action внутри серверного компонента

Next.js 16 App Router, cacheComponents не включен. Тема хранится в cookie браузера; база данных не нужна.

// app/page.tsx
import { cookies } from "next/headers";
 
export default async function Page() {
  async function saveTheme(formData: FormData) {
    "use server";
 
    const theme = formData.get("theme");
    if (theme !== "light" && theme !== "dark") {
      throw new Error("Недопустимая тема");
    }
 
    const cookieStore = await cookies();
    cookieStore.set("theme", theme, {
      httpOnly: true,
      sameSite: "lax",
      secure: process.env.NODE_ENV === "production",
      path: "/",
    });
  }
 
  const theme = (await cookies()).get("theme")?.value ?? "light";
  return (
    <form action={saveTheme}>
      <p>Сохраненная тема: {theme}</p>
      <label htmlFor="theme">Тема оформления</label>
      <select id="theme" name="theme" defaultValue={theme}>
        <option value="light">Светлая</option>
        <option value="dark">Темная</option>
      </select>
      <button type="submit">Сохранить</button>
    </form>
  );
}

Форма передает значение в FormData. Action проверяет его и устанавливает cookie, после чего Next.js обновляет серверный результат.

Пример: Actions в отдельном файле

// app/actions.ts
"use server";
 
import { cookies } from "next/headers";
 
export async function saveLanguage(formData: FormData) {
  const language = formData.get("language");
  if (language !== "ru" && language !== "en") {
    throw new Error("Выберите поддерживаемый язык");
  }
  (await cookies()).set("language", language, {
    path: "/",
    httpOnly: true,
    sameSite: "lax",
    secure: process.env.NODE_ENV === "production",
  });
}
// app/page.tsx
import { saveLanguage } from "./actions";
 
export default function Page() {
  return <form action={saveLanguage}>
    <label htmlFor="language">Язык</label>
    <select id="language" name="language">
      <option value="ru">Русский</option>
      <option value="en">English</option>
    </select>
    <button type="submit">Сохранить</button>
  </form>;
}

Отдельного fetch нет. Файл с "use server" в начале экспортирует только серверные функции, и их можно импортировать в клиентские компоненты.

Что важно помнить

  • "use server" не проверяет пользователя. Для изменения аккаунта, заказа или другой защищенной записи Action сам проверяет сессию и права на конкретную операцию. Скрытая кнопка не заменяет проверку.
  • Данные из FormData — недоверенный ввод: валидируй их (например, Zod).
  • Форма с Action, заданная в Server Component, работает и без клиентского JavaScript (progressive enhancement). Это не распространяется на произвольный onClick.
  • Мобильному приложению или внешнему сервису удобнее Route Handler со стабильным URL и HTTP-контрактом: Actions тесно связаны с интерфейсом Next.js.
  • После мутации обновляй кэш: revalidatePath, revalidateTag или updateTag.

Мини-шпаргалка

  • Action = async-функция с "use server", передается в <form action>.
  • Выполняется на сервере через POST, организованный Next.js.
  • Проверки ввода и прав — внутри Action.
  • Для внешних клиентов — Route Handlers.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам