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.