Что такое form actions в SvelteKit и как они работают?

Form Actions в SvelteKit

Form Actions — механизм обработки HTML-форм на сервере без написания отдельных API-эндпоинтов. Они работают через нативный <form method="POST"> и обрабатываются в +page.server.ts. После выполнения SvelteKit автоматически обновляет данные страницы.

Структура actions

Экспортируйте объект actions из +page.server.ts. Ключ default — для форм без атрибута action; именованные actions вызываются через action="?/name".

// src/routes/contact/+page.server.ts
import { fail, redirect } from '@sveltejs/kit';
import type { Actions } from './$types';

export const actions: Actions = {
  // Дефолтное действие — POST /contact
  default: async ({ request, locals }) => {
    const data = await request.formData();
    const name = data.get('name') as string;
    const email = data.get('email') as string;
    const message = data.get('message') as string;

    // Валидация
    const errors: Record<string, string> = {};
    if (!name) errors.name = 'Name is required';
    if (!email || !email.includes('@')) errors.email = 'Valid email required';
    if (!message) errors.message = 'Message is required';

    if (Object.keys(errors).length) {
      // fail() сохраняет введённые данные и ошибки в $page.form
      return fail(422, { errors, values: { name, email, message } });
    }

    await db.messages.create({ name, email, message });
    throw redirect(303, '/contact/success');
  }
};

Именованные actions

// src/routes/profile/+page.server.ts
export const actions: Actions = {
  updateName: async ({ request, locals }) => {
    if (!locals.user) throw error(401);
    const data = await request.formData();
    const name = data.get('name') as string;
    await db.users.update(locals.user.id, { name });
    return { success: true };
  },

  deleteAccount: async ({ locals, cookies }) => {
    if (!locals.user) throw error(401);
    await db.users.delete(locals.user.id);
    cookies.delete('session', { path: '/' });
    throw redirect(303, '/');
  }
};

Форма в компоненте

// src/routes/contact/+page.svelte
<script lang="ts">
  import { enhance } from '$app/forms';
  import type { ActionData } from './$types';

  export let form: ActionData; // Данные из fail() или action
</script>

<form method="POST" use:enhance>
  <label>
    Name
    <input name="name" value={form?.values?.name ?? ''} />
    {#if form?.errors?.name}<span class="error">{form.errors.name}</span>{/if}
  </label>

  <label>
    Email
    <input name="email" type="email" value={form?.values?.email ?? ''} />
  </label>

  <textarea name="message">{form?.values?.message ?? ''}</textarea>

  <!-- Именованное действие -->
  <button formaction="?/updateName">Update Name</button>
  <button>Send (default action)</button>
</form>

use:enhance — прогрессивное улучшение

Директива use:enhance из $app/forms перехватывает submit, делает fetch вместо полного перезапуска страницы и обновляет $page.form реактивно. Без неё форма работает как обычный HTML-form (полная перезагрузка).

import { enhance } from '$app/forms';

// Расширенный enhance с колбэками
<form
  method="POST"
  use:enhance={({ formData, cancel }) => {
    // Вызывается перед отправкой
    // cancel() отменяет запрос
    return async ({ result, update }) => {
      // result.type: 'success' | 'failure' | 'redirect' | 'error'
      if (result.type === 'success') {
        showToast('Sent!');
      }
      await update(); // Обновляет $page.form и данные страницы
    };
  }}
>

Подводные камни

• fail() должен возвращать сериализуемые данные — Date, классы с методами, undefined вызовут ошибку сериализации.
• После успешного action SvelteKit по умолчанию делает invalidateAll() и обновляет страницу — если action возвращает данные (не redirect), они попадают в form, но data (из load) тоже перезапрашивается.
• Именованные actions нельзя использовать с дефолтным <button> без formaction — default action вызывается только если нет явного formaction.
• Без use:enhance форма делает полную перезагрузку страницы; $page.form в Svelte-компоненте обновляется только с use:enhance.
• Actions доступны только из +page.server.ts, не из +page.ts — load в .ts файле не может содержать actions.
• При отправке файлов (enctype="multipart/form-data") размер ограничен настройкой адаптера; по умолчанию Node-адаптер принимает до ~1MB.
• При использовании redirect() внутри action убедитесь, что статус 303 (а не 301/302) — браузер изменит метод на GET, что и нужно после POST.

• Путать form actions с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «form actions».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.