Server Actions

Server Function ve Server Action

React rehberindeki Actions dersinde Action'ı tarayıcıda çalıştırdınız. Server Function, "use server" ile işaretlenmiş ve sunucuda çalışan async bir fonksiyondur. Bir form'a ya da transition'a bağlandığında adı Server Action olur.¹

İstemci onu bir ağ isteğiyle çağırır. Next.js bu isteği sizin yerinize kurar: bir API route, fetch ya da JSON ayrıştırma yazmazsınız.¹

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

import { updateTag } from "next/cache";

export async function addReview(formData: FormData) {
  const text = String(formData.get("text"));
  await db.review.create({ data: { text } });
  updateTag("reviews");
}

// app/products/[slug]/page.tsx
import { addReview } from "@/app/actions";

<form action={addReview}>
  <textarea name="text" aria-label="Yorumunuz" required />
  <button>Gönder</button>
</form>;

"use server" dosyanın başındaysa tüm export'lar Server Function olur. Client Component'ler Server Function tanımlayamaz ama böyle bir dosyadan import edip kullanabilir.¹

Server Component'teki form JavaScript yüklenmeden de gönderilir (progressive enhancement). Client Component'te ise JavaScript yüklenene kadar gönderim sıraya alınır.¹

Sonucu Göstermek: useActionState

Hata ya da başarı mesajı göstermek için Action'ı React'in useActionState'ine verin. Action bu durumda ilk argüman olarak önceki state'i alır.¹²

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

export type SubscribeState = { message: string | null };

export async function subscribe(
  _prev: SubscribeState,
  formData: FormData,
): Promise<SubscribeState> {
  const email = String(formData.get("email"));
  if (!email.includes("@")) return { message: "Geçerli bir e-posta girin." };

  await db.subscriber.create({ data: { email } });
  return { message: "Abone oldunuz." };
}

// components/subscribe-form.tsx
"use client";

import { useActionState } from "react";

import { subscribe } from "@/app/actions";

export function SubscribeForm() {
  const [state, formAction, isPending] = useActionState(subscribe, { message: null });

  return (
    <form action={formAction}>
      <input name="email" type="email" aria-label="E-posta" />
      <button disabled={isPending}>Abone ol</button>
      {state.message && <p role="status">{state.message}</p>}
    </form>
  );
}

Doküman beklenen hatalar için throw yerine değer döndürmeyi önerir. throw en yakın hata sınırına gider; doğrulama hatası için fazla sert.³ Alan bazlı doğrulama ve Zod şeması Formlar rehberinde.

Mutation'dan Sonra Ne Yenilenmeli

Next.js, Action'ı ve güncellenen sayfayı tek istekte döndürebilir. Hangisinin yenileneceğini Action'da çağırdığınız fonksiyon belirler:⁴

Kullanıcı kendi yaptığı değişikliği hemen görmeli ise (sepete ekleme, yorum yazma) updateTag doğru seçimdir. redirect'i her zaman yenileme çağrılarından sonra yazın.⁴

Güvenlik: Her Action Açık Bir Uç Noktadır

"use server", fonksiyonu bir POST uç noktasına çevirir. Sayfanızda form göstermeseniz bile herkes aynı isteği elle gönderebilir.⁴ Sebastian Markbåge'ın Next.js güvenlik yazısındaki kural: Server Action'ları dışarıya açık bir API gibi ele alın.⁵

Next.js kendi tarafında birkaç koruma sağlar: Origin ile Host'u karşılaştırıp CSRF'i engeller, istek gövdesini varsayılan 1 MB ile sınırlar, kullanılmayan Action'ları paketten çıkarır ve Action kimliklerini şifreler.⁴ Ama uygulamanın kendi kontrolleri sizin işiniz:

"use server";

export async function deleteReview(reviewId: string) {
  const user = await getCurrentUser();
  const review = await db.review.findFirst({
    where: { id: reviewId, authorId: user.id },
  });
  if (!review) return { error: "Yorum bulunamadı." };

  await db.review.delete({ where: { id: review.id } });
  updateTag("reviews");
  return { error: null };
}

Rol kontrolünü tek yerde toplamak Yetkilendirme ve roller dersinde.

Ne Zaman Action, Ne Zaman Başka Bir Şey

Next.js bir istemcideki Action'ları sırayla çalıştırır; ikincisi birincinin bitmesini bekler. Promise.all ile Action'ları paralel çağırmak işe yaramaz.⁴

Kendin Dene

• addReview'u bir Server Component'teki forma bağlayın. Tarayıcıda JavaScript'i kapatıp formu gönderin.

• SubscribeForm'a @ içermeyen bir adres girin; mesajın sayfa yenilenmeden geldiğini görün.

• Aynı Action'da updateTag yerine revalidateTag(..., "max") kullanın. Yorum listesi hemen güncelleniyor mu?

• DevTools'un Network sekmesinde Action isteğini bulun. Bu isteği curl ile tekrarlayabilir misiniz? deleteReview'daki sahiplik kontrolü neden şart?

Detaylı Öğrenmek İçin

• Resmi doküman: "Server Actions and Mutations" rehberi; tek istekte veri ve arayüz, sıralı çalıştırma, güvenlik ve deploy notları.⁴

• Yazı: Sebastian Markbåge, "How to Think About Security in Next.js"; Server Component ve Action'larda güvenlik modeli.⁵

• Resmi doküman: "Data Security" rehberi; Data Access Layer, girdi doğrulama, rate limit ve dönüş değerini kısıtlamak.⁶

• Video: Aurora Scharff, "Enhancing Forms with React Server Components"; Server Component ve Action'larla form deneyimini adım adım iyileştirmek.⁷