Введение в Server Actions

1. Знакомство с Server Actions

Server Actions — это относительно новая фича в Next.js (начиная с 13-й версии, но особенно раскрывающаяся в 15-й), которая позволяет вызывать серверный код напрямую из компонентов, минуя ручное создание API-эндпоинтов. Если коротко: это функции, которые выполняются на сервере, но вызываются из клиентского или серверного компонента как обычные JavaScript-функции.

Простой пример

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

export async function addTodo(formData: FormData) {
  // Здесь можно обращаться к базе данных, файловой системе и т.д.
  // Всё это выполняется только на сервере!
}

Server Actions — это как супергерой среди функций: они не видны пользователю, но могут делать всё самое секретное и важное на сервере — например, работать с БД, секретами, файлами и т.д.

Классическая схема: API-эндпоинты

До появления Server Actions, чтобы, например, добавить новую задачу в список, приходилось:

1. Создавать API-эндпоинт (например, /api/todos).
2. Отправлять POST-запрос через fetch/axios из компонента.
3. На сервере разбирать запрос, выполнять нужные действия, возвращать ответ.
4. На клиенте обрабатывать ответ, обновлять состояние.

Это работает, но выглядит как "лишний слой" — много повторяющегося кода, ручное описание API, обработка ошибок, сериализация данных туда-обратно.

Server Actions: новая парадигма

Server Actions позволяют:

• Вызывать серверные функции напрямую из компонентов, без fetch, без ручного API.
• Передавать данные формы или другие параметры в action-функцию — и сразу работать с ними на сервере.
• Обрабатывать результат на сервере, возвращать результат прямо в компонент.
• Безопасно работать с секретами (ключи, доступ к БД) — код Server Action никогда не попадёт в браузер.

Это похоже на магию: вы описываете функцию с директивой 'use server', а Next.js сам делает всё остальное — сериализацию, маршрутизацию, безопасность.

2. Как это выглядит на практике?

Пример: добавление задачи через Server Action

Давайте рассмотрим, как выглядел бы код добавления задачи в список дел (ToDo) с помощью Server Action.

Определяем серверную функцию

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

export async function addTodo(formData: FormData) {
  const title = formData.get('title');
  // Здесь можно, например, добавить задачу в базу данных
  // await db.todos.create({ title });
}

Используем action в форме

// app/page.tsx (Server Component)
import { addTodo } from './actions';

export default function Page() {
  return (
    <form action={addTodo}>
      <input name="title" placeholder="Новая задача" />
      <button type="submit">Добавить</button>
    </form>
  );
}

Что происходит?
— При отправке формы вызывается функция addTodo на сервере, Next.js сам передаёт ей данные формы.
— Вся обработка происходит на сервере, никакого fetch вручную писать не нужно.
— После выполнения action-компонент автоматически перерисовывается (или можно обновить состояние через useFormState — об этом позже).

3. Полезные нюансы

Где выполняются Server Actions?

Только на сервере! Даже если вы импортируете Server Action в клиентский компонент, сам вызов всегда отправляет данные на сервер, функция не попадёт в bundle для браузера.

• Можно безопасно использовать секреты, переменные окружения, приватные ключи.
• Невозможно случайно "утянуть" серверную логику в браузер (если вы не забудете 'use server').

Как объявлять Server Action?

Server Action — это обычная async-функция, но в файле или модуле обязательно должна быть директива 'use server' в начале. Если забыть — функция будет работать на клиенте (или вообще не будет работать).

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

export async function updateProfile(formData: FormData) {
  // только сервер!
}

Можно объявлять Server Actions прямо внутри компонента (если компонент серверный) или импортировать их из отдельного файла.

Кратко: преимущества Server Actions

• Простота: не нужно вручную писать API-эндпоинты, fetch-запросы, сериализовать данные.
• Безопасность: серверный код не попадает в браузер.
• Скорость разработки: меньше бойлерплейта, меньше ошибок.
• Интеграция с формами: можно передавать FormData напрямую, не возиться с JSON.

Когда использовать Server Actions?

• Когда нужно обработать данные формы (регистрация, добавление/удаление задачи, комментария и т.д.).
• Когда важна безопасность: работа с БД, секретами, приватными API.
• Когда хочется упростить архитектуру и избавиться от лишних API-эндпоинтов.

Когда не стоит:
— Для сложных, многоступенчатых API (например, когда нужен REST или GraphQL для мобильных приложений).
— Когда требуется совместимость с внешними клиентами (не Next.js), которым нужен API.

Визуализация: как это работает

+---------------------------+        +----------------------------+
|      Браузер/Клиент      |  --->   |         Сервер             |
|--------------------------|         |----------------------------|
| <form action={action}>   |         | export async function ...  |
|   [submit]               |         |   // обработка             |
+--------------------------+         +----------------------------+
        | POST FormData                   | Выполнение action
        |-------------------------------->| 
        | <----------[Ответ/Перерисовка]--|

• Пользователь отправляет форму.
• Next.js отправляет данные на сервер, вызывает Server Action.
• Сервер обрабатывает данные, возвращает результат, компонент обновляется.

4. Типичные ошибки при работе с Server Actions

Ошибка №1: забыли директиву 'use server'.
Если не указать 'use server' в файле с action, функция будет выполняться на клиенте, и вы получите ошибку или странное поведение. Всегда проверяйте, что в начале файла есть эта директива.

Ошибка №2: попытка использовать Server Action в Client Component без правильного импорта.
Server Actions можно вызывать из Client Components, но только если они объявлены с 'use server' и корректно импортированы. Не пытайтесь писать серверный код прямо в файле с 'use client' — ничего хорошего не выйдет!

Ошибка №3: работа с несуществующими полями FormData.
Если вы опечатались в имени поля формы (formData.get('tittle') вместо 'title'), получите null или ошибку. Внимательно следите за соответствием имён.

Ошибка №4: попытка использовать браузерные API внутри Server Action.
В Server Action нельзя использовать window, document и прочие браузерные объекты — они доступны только на клиенте! Если вы попытаетесь это сделать, получите ошибку на этапе сборки или выполнения.

Ошибка №5: ожидание, что Server Action выполнится мгновенно.
Поскольку Server Action — это серверный вызов, между клиентом и сервером всегда есть задержка (пусть и минимальная). Не забывайте обрабатывать загрузку, ошибки, обновление UI.