Розбираємо, коли брати Server Actions, а коли Route Handlers у Next.js 16. Порівняльна таблиця, приклади коду для форм і вебхуків Stripe, а також покроковий план міграції з pages/api за 4–8 днів.
Оновлено: 20 липня 2026
У Next.js 16 Server Actions — це асинхронні серверні функції, які React викликає прямо з компонента, а Route Handlers — це класичні HTTP-ендпоінти у файлах route.ts. Коротка відповідь: якщо мутацію ініціює ваш власний UI, беріть Server Action; якщо запит іде ззовні (вебхук, мобільний застосунок, публічний API), беріть Route Handler. Ці два інструменти не конкурують, вони розв'язують різні задачі, і в реальному проєкті ви майже завжди використовуєте обидва.
no-store); для кешування використовуйте export const dynamic = 'force-static' або "use cache".pages/api/* на комбінацію Server Actions + Route Handlers у типовому SaaS займає 3–7 днів на розробника залежно від кількості мутацій.Server Actions це серверні функції з директивою "use server", які React перетворює на прихований POST-запит у момент виклику. Ви пишете код так, ніби це звичайна функція, а фреймворк робить серіалізацію аргументів, генерує захищений ідентифікатор дії, шифрує його ключем NEXT_SERVER_ACTIONS_ENCRYPTION_KEY, перевіряє same-origin і CSRF-токен, а потім повертає нові UI-фрагменти в тій же відповіді. Це модель, дуже близька до RPC (remote procedure call), тільки без ручного визначення схеми ендпоінту.
Route Handlers це традиційні REST-подібні маршрути у файлах app/api/*/route.ts, які експортують іменовані функції GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Ви працюєте з нативними об'єктами Web Request і Response, тобто той самий код теоретично можна перенести на Cloudflare Workers, Bun чи Deno. Route Handlers у Next.js 16 замінили колишні pages/api/*-роути з App Router-ери й підтримують як Node.js, так і Edge Runtime через export const runtime = 'edge'.
Ключова відмінність філософії: Server Actions function-first, вони існують у контексті React-компонента; Route Handlers URL-first, вони існують як публічно адресована точка на HTTP-мапі вашого сервера. Ви не можете відкрити Server Action у Postman чи вставити його в іншу систему через URL, і це не баг, а фіча.
| Характеристика | Server Actions | Route Handlers |
|---|---|---|
| Виклик з мобільного/зовнішнього клієнта | Неможливо | Так, публічний URL |
| Підтримка вебхуків (Stripe, GitHub) | Ні | Основний випадок використання |
| HTTP-методи | Тільки POST (внутрішньо) | GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| CSRF-захист | Вбудований, зашифровані ID | Реалізуєте самі (SameSite cookies + токен) |
| End-to-end type safety | Так (TS-типи «протікають») | Ні, тип втрачається на HTTP-межі |
| Progressive enhancement форм | Так, працює без JS | Тільки з client-side fetch |
| Кешування GET-відповідей | Не застосовно | Динамічно за замовчуванням у 16, opt-in через "use cache" |
| Streaming responses (SSE, чат) | Обмежено (через RSC-стрім) | Повна підтримка ReadableStream |
| Тестування через Postman/curl | Неможливо | Природно |
| Rate limiting на рівні gateway | Складно (немає стабільного URL) | Легко (кожен ендпоінт має URL) |
Правило, за яким я скеровую команди під час міграцій: Server Action за замовчуванням для будь-якої мутації, яку викликає ваш React UI. Це форми реєстрації, кнопки «зберегти», лайки, delete-кнопки в адмінці, оптимістичні лічильники, тогл-перемикачі налаштувань. Все, що починається з кліку у вашому власному фронтенді і має змінити стан на сервері, це кандидат на Server Action.
Чесно, коли я вперше переписав пів дашборда з fetch('/api') на Server Actions, найбільше вразило скорочення файлів. Технічні переваги, які реально економлять час:
JSON.stringify і JSON.parse.action={updateProfile} надсилається навіть тоді, коли JavaScript ще не завантажився або зламався в старому Safari.revalidatePath('/dashboard') усередині дії, і клієнт отримує оновлений RSC-payload у тій же відповіді, без другого запиту.Приклад із useActionState та Zod-валідацією, типова форма створення проєкту:
// app/projects/actions.ts
'use server'
import { z } from 'zod'
import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
const CreateProject = z.object({
name: z.string().min(3).max(80),
visibility: z.enum(['public', 'private']),
})
export async function createProject(_prev: unknown, formData: FormData) {
const session = await auth()
if (!session) return { error: 'Unauthorized' }
const parsed = CreateProject.safeParse({
name: formData.get('name'),
visibility: formData.get('visibility'),
})
if (!parsed.success) {
return { fieldErrors: parsed.error.flatten().fieldErrors }
}
const project = await db.project.create({
data: { ...parsed.data, ownerId: session.userId },
})
revalidatePath('/projects')
redirect(`/projects/${project.id}`)
}// app/projects/new/page.tsx
'use client'
import { useActionState } from 'react'
import { createProject } from '../actions'
export default function NewProjectForm() {
const [state, action, pending] = useActionState(createProject, null)
return (
<form action={action}>
<input name="name" required />
{state?.fieldErrors?.name && <p>{state.fieldErrors.name.join(', ')}</p>}
<select name="visibility" defaultValue="private">
<option value="private">Приватний</option>
<option value="public">Публічний</option>
</select>
<button disabled={pending}>Створити</button>
</form>
)
}Глибший розбір цього патерну я вже давав у статті про безпечну валідацію форм із Zod та useActionState, там є повний ланцюжок від FormData до useOptimistic.
Route Handler це правильний вибір, коли клієнт вашого коду не є вашим React-компонентом. Найпоширеніші сценарії:
?code= у query-string. Це завжди GET-Route Handler.ReadableStream, headers і статус-кодами.Authorization: Bearer./api/healthz, а не React-компонент.Приклад безпечного вебхука Stripe із верифікацією підпису та ідемпотентністю (я цей самий шаблон використовував у трьох останніх проєктах):
// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from 'next/server'
import Stripe from 'stripe'
import { db } from '@/lib/db'
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
const WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET!
export const runtime = 'nodejs' // Stripe SDK потребує Node
export async function POST(req: NextRequest) {
const body = await req.text() // raw body для перевірки підпису
const signature = req.headers.get('stripe-signature')
if (!signature) return new NextResponse('Missing signature', { status: 400 })
let event: Stripe.Event
try {
event = stripe.webhooks.constructEvent(body, signature, WEBHOOK_SECRET)
} catch (err) {
return new NextResponse('Invalid signature', { status: 400 })
}
// Ідемпотентність: Stripe може ретраїти той самий event
const seen = await db.processedEvent.findUnique({ where: { id: event.id } })
if (seen) return NextResponse.json({ received: true })
await db.processedEvent.create({ data: { id: event.id, type: event.type } })
if (event.type === 'checkout.session.completed') {
const session = event.data.object as Stripe.Checkout.Session
await db.subscription.upsert({
where: { userId: session.metadata!.userId },
create: { userId: session.metadata!.userId, status: 'active' },
update: { status: 'active' },
})
}
return NextResponse.json({ received: true })
}Так, але тільки в частині CSRF та випадкового експозу, не в частині авторизації. Server Actions мають три вбудовані шари, які на Route Handler ви маєте реалізувати самі:
updateUser, зловмисник бачить непередбачуваний хеш, згенерований NEXT_SERVER_ACTIONS_ENCRYPTION_KEY. Замінити його чи «підкластися» через інший action ID неможливо без ключа.Origin із поточним доменом і відхиляє запити з чужих сайтів. Це блокує класичну CSRF-схему «форма на evil.com POST-ить на bank.com».Але жоден із цих шарів не відповідає на питання «а чи має цей користувач право видаляти цей документ?». Це ваша відповідальність, і вона однакова для Server Actions і для Route Handlers. Завжди починайте функцію з перевірки сесії та ACL. Подібно, вбудований CSRF-захист не рятує від XSS: якщо зловмисний скрипт виконується в тому ж origin, він може викликати ваш Server Action, як і будь-який ваш власний код.
Окрема тема, міграція middleware.ts на proxy.ts та інцидент CVE-2025-29927: там я показував, чому не варто робити авторизацію лише в middleware і чому кожен Server Action чи Route Handler мусить перевіряти сесію самостійно як defense-in-depth.
У більшості реальних сценаріїв так, але різниця приходить не з HTTP-стеку, а з архітектури React Server Components. Коли ви викликаєте Server Action і в ньому робите revalidatePath, відповідь на той самий POST-запит містить одразу і результат мутації, і оновлені RSC-фрагменти для UI. Класичний REST-флоу вимагає двох запитів: POST для мутації, потім GET (або SWR-ревалідація), щоб оновити дані.
Кілька цифр із моєї практики міграцій:
fetch('/api/tasks', {method:'POST'}) плюс mutate('/api/tasks') на один Server Action із revalidateTag('tasks') знижує time-to-updated-UI з ~450 мс до ~180 мс у 4G Fast.Але є нюанси. Server Actions завжди йдуть через POST і не кешуються на CDN. Якщо ваш ендпоінт це прочитання публічних даних, які змінюються раз на годину (наприклад, «топ-10 постів»), Route Handler із export const revalidate = 3600 або з "use cache" буде дешевшим і швидшим у більшому масштабі, бо CDN віддасть його з edge-локації. Server Action на таке взагалі не годиться, це не для читань, а для мутацій.
Найздоровіша типова архітектура застосунку на Next.js 16 виглядає так:
"use cache" для читань, які показує ваш React UI. Ніяких REST-роутів, ніяких клієнтських fetch. Дані читаються прямо з БД у серверному компоненті.app/api/* тонкий шар для зовнішнього світу: /api/webhooks/stripe, /api/webhooks/github, /api/mobile/v1/*, /api/auth/callback/*, /api/og (генерація OG-картинок), /api/healthz.Такий поділ дає найкраще з обох світів: DX і швидкість Server Actions для 90% мутацій, і повний контроль над HTTP там, де він реально потрібен. Дотично: якщо ви будуєте складний UI із модалками поверх існуючих сторінок, подивіться в бік паралельних та перехоплених маршрутів у Next.js 16, це майже завжди чистіше, ніж окремий Route Handler для рендера модального контенту.
Оскільки я допомагав кільком командам мігрувати з pages/api на комбінацію Server Actions + Route Handlers, дам приблизний бюджет часу. Ці цифри валідовані на 5+ проєктах розміром 50–200 API-ендпоінтів:
pages/api/* і розкласифікуйте: (a) мутації від власного UI → Server Actions, (b) вебхуки та зовнішні виклики → залишити як Route Handlers, (c) читання, які фактично використовуються лише в UI → перенести в Server Components.pages/api/foo.ts стають app/api/foo/route.ts. Змініть сигнатуру: замість (req, res) => … експортуйте іменовані GET/POST. req.body стає await req.json(), res.status(200).json(x) стає NextResponse.json(x).fetch('/api/tasks', {method:'POST', body: JSON.stringify(data)}) плюс ручний setState плюс toast стає <form action={createTask}> плюс useActionState. Викидайте SWR/React Query hooks, які тепер зайві.export const revalidate або "use cache".NEXT_SERVER_ACTIONS_ENCRYPTION_KEY заданий в env продакшена (Vercel робить це автоматично, самохост ні). Перевірте, що кожен новий Server Action робить auth-перевірку. Додайте rate-limit на публічні Route Handlers.Разом: 4–8 днів на розробника для типового SaaS із ~50 мутаційними ендпоінтами. Найдовше зазвичай не сам код, а retest UI-флоу і виправлення тонких кейсів із revalidateTag.
Офіційна документація по Server Actions та Mutations і по Route Handlers у App Router обов'язкове читання перед міграцією; там є всі граничні кейси з cookies(), headers() та runtime-налаштуваннями.
Ні. Server Actions не мають публічного URL, не підтримують GET та інші HTTP-методи, окрім POST, і не можуть приймати зовнішні виклики. Для вебхуків, мобільних клієнтів, OAuth-callbacks і будь-якого публічного API потрібні Route Handlers.
Так. Клієнтський компонент імпортує серверну функцію з файлу з директивою 'use server' угорі і викликає її як звичайну функцію. Next.js під капотом робить POST-запит, серіалізує аргументи та повертає відповідь. Тип аргументів і повернення зберігається наскрізно.
Ні, він генерується та перевіряється фреймворком автоматично. Ви не бачите його у власному коді. Крім того, Next.js перевіряє заголовок Origin і шифрує ідентифікатор дії ключем NEXT_SERVER_ACTIONS_ENCRYPTION_KEY, тож класичні CSRF-сценарії заблоковані з коробки.
Ні, Server Actions завжди йдуть через POST і не кешуються ні браузером, ні CDN. Це навмисно, щоб уникнути помилкового кешування мутацій. Якщо вам потрібне кешоване читання, використовуйте Server Component з директивою "use cache" або GET Route Handler з export const revalidate.
Технічно можна повертати ReadableStream через RSC-стрім, але це погана ідея для довгих стрімів LLM: втрачаєте контроль над backpressure, cancellation і не можете легко перевикористати ендпоінт із мобільного клієнта. Для чатів LLM і SSE ставте окремий Route Handler з export const runtime = 'edge'.
Route Handlers. Мобільний застосунок не може викликати Server Action, у нього немає React Server Components runtime. Створіть окремий префікс на кшталт /api/mobile/v1/* з версіонуванням, JSON-контрактом та Bearer-авторизацією. Server Actions залишаться для web-UI.
Як створити безпечні форми в Next.js App Router: Zod-валідація, useActionState, автентифікація, авторизація та next-safe-action — з прикладами коду для продакшну.