React 19 Actions 실전 가이드: useActionState·useFormStatus·useOptimistic으로 라이브러리 없이 폼과 낙관적 UI 구현하기

sequenceDiagram
    participant 사용자
    participant 폼
    participant React
    participant 서버
 
    사용자->>폼: 제출 클릭
    폼->>React: action 함수 호출
    React->>React: isPending = true 시작
    React->>서버: API 요청 전송
    Note over React: React 18은 비동기 지원 부재로<br/>이 시점에 isPending = false
    Note over React: React 19는 비동기 완료까지<br/>isPending = true 유지
    서버-->>React: 응답 반환
    React->>React: state 업데이트, 폼 리셋
    React->>React: isPending = false
    React-->>폼: 새 state로 리렌더

const [state, dispatch, isPending] = useActionState(actionFn, initialState);

// 모든 분기에서 동일한 형태 반환
async function signupAction(
  prevState: { error: string | null; success: boolean },
  formData: FormData
) {
  const name = formData.get("name") as string;
 
  if (!name) {
    return { error: "이름을 입력해 주세요.", success: false };
  }
 
  try {
    await saveUser(name);
    return { error: null, success: true };
  } catch {
    return { error: "서버 오류가 발생했습니다.", success: false };
  }
}

const { pending, data, method, action } = useFormStatus();

// 어떤 <form> 안에든 넣으면 자동으로 폼 상태를 구독합니다
function SubmitButton({ label }: { label: string }) {
  const { pending } = useFormStatus();
 
  return (
    <button type="submit" disabled={pending}>
      {pending ? "처리 중..." : label}
    </button>
  );
}

const [optimisticState, addOptimistic] = useOptimistic(
  actualState,
  (currentState, optimisticValue) => newState
);

import { useActionState } from "react";
import { useFormStatus } from "react-dom";
 
type FormState = {
  error: string | null;
  success: boolean;
};
 
const initialState: FormState = { error: null, success: false };
 
async function signupAction(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const name = formData.get("name") as string;
  const email = formData.get("email") as string;
 
  if (!name || !email) {
    return { error: "모든 필드를 입력해 주세요.", success: false };
  }
 
  try {
    await registerUser({ name, email });
    return { error: null, success: true };
  } catch {
    return { error: "가입 중 오류가 발생했습니다.", success: false };
  }
}
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "가입 처리 중..." : "가입하기"}
    </button>
  );
}
 
export function SignupForm() {
  const [state, dispatch] = useActionState(signupAction, initialState);
 
  if (state.success) {
    return <p>가입이 완료되었습니다!</p>;
  }
 
  return (
    <form action={dispatch}>
      <input name="name" type="text" placeholder="이름" required />
      <input name="email" type="email" placeholder="이메일" required />
      {state.error && <p style={{ color: "red" }}>{state.error}</p>}
      <SubmitButton />
    </form>
  );
}

import { useState } from "react";
import { useOptimistic } from "react";
 
async function toggleLike(
  postId: string
): Promise<{ count: number; isLiked: boolean }> {
  const res = await fetch(`/api/posts/${postId}/like`, { method: "POST" });
  return res.json();
}
 
export function LikeButton({
  postId,
  initialLikes,
  initialIsLiked,
}: {
  postId: string;
  initialLikes: number;
  initialIsLiked: boolean;
}) {
  const [likes, setLikes] = useState(initialLikes);
  const [isLiked, setIsLiked] = useState(initialIsLiked);
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    likes,
    (currentLikes: number, delta: number) => currentLikes + delta
  );
 
  // <form action={...}>이 트랜지션을 열어주므로 addOptimisticLike 호출이 동작합니다
  async function handleLike() {
    const delta = isLiked ? -1 : 1;
    addOptimisticLike(delta);
    try {
      const updated = await toggleLike(postId);
      setLikes(updated.count);
      setIsLiked(updated.isLiked);
    } catch {
      // actualState(likes)가 변하지 않으므로 optimisticLikes가 자동으로 복구됩니다
      // 실제 서비스에서는 에러 토스트 등 사용자 알림을 추가하세요
    }
  }
 
  return (
    <form action={handleLike}>
      <button type="submit">
        {optimisticLikes} {isLiked ? "❤️" : "🤍"}
      </button>
    </form>
  );
}

// app/posts/actions.ts
"use server";
 
import { revalidatePath } from "next/cache";
import { db } from "@/lib/db";
 
type PostFormState = {
  error: string | null;
  success: boolean;
};
 
export async function createPostAction(
  prevState: PostFormState,
  formData: FormData
): Promise<PostFormState> {
  const title = formData.get("title") as string;
  const content = formData.get("content") as string;
 
  if (!title?.trim()) {
    return { error: "제목을 입력해 주세요.", success: false };
  }
 
  try {
    await db.post.create({ data: { title, content } });
    revalidatePath("/posts");
    return { error: null, success: true };
  } catch {
    return { error: "포스트 저장에 실패했습니다.", success: false };
  }
}

// app/posts/PostForm.tsx
"use client";
 
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
import { createPostAction } from "./actions";
 
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "저장 중..." : "발행하기"}
    </button>
  );
}
 
export default function PostForm() {
  const [state, action] = useActionState(createPostAction, {
    error: null,
    success: false,
  });
 
  return (
    <form action={action}>
      <input name="title" type="text" placeholder="제목" />
      <textarea name="content" placeholder="내용" />
      {state.error && <p>{state.error}</p>}
      {state.success && <p>포스트가 발행되었습니다!</p>}
      <SubmitButton />
    </form>
  );
}

import { useActionState, useOptimistic } from "react";
import { useFormStatus } from "react-dom";
 
type Comment = { id: string; text: string; author: string };
type CommentState = { comments: Comment[]; error: string | null };
 
async function postComment(text: string): Promise<Comment> {
  const res = await fetch("/api/comments", {
    method: "POST",
    body: JSON.stringify({ text }),
    headers: { "Content-Type": "application/json" },
  });
  if (!res.ok) throw new Error("댓글 저장 실패");
  return res.json();
}
 
async function addCommentAction(
  prevState: CommentState,
  formData: FormData
): Promise<CommentState> {
  const text = formData.get("text") as string;
  try {
    const newComment = await postComment(text);
    return { comments: [...prevState.comments, newComment], error: null };
  } catch {
    return { comments: prevState.comments, error: "댓글 등록에 실패했습니다." };
  }
}
 
function CommentSubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "등록 중..." : "댓글 달기"}
    </button>
  );
}
 
export function CommentSection({
  initialComments,
}: {
  initialComments: Comment[];
}) {
  const [state, dispatch] = useActionState(addCommentAction, {
    comments: initialComments,
    error: null,
  });
  const [optimisticComments, addOptimistic] = useOptimistic(
    state.comments,
    (current: Comment[], newComment: Comment) => [...current, newComment]
  );
 
  // <form action={dispatch}>에 바로 연결하면 addOptimistic을 호출할 기회가 없습니다.
  // 이 래퍼 함수는 <form action={...}>이 열어주는 트랜지션 안에서 실행되므로
  // addOptimistic 호출이 유효하고, 이어서 dispatch(formData)가 실제 액션을 트리거합니다.
  // 임시 댓글(temp-*)은 addCommentAction이 완료되어 state.comments가 갱신될 때까지 유지됩니다.
  async function handleSubmit(formData: FormData) {
    const text = formData.get("text") as string;
    addOptimistic({ id: `temp-${Date.now()}`, text, author: "나" });
    dispatch(formData);
  }
 
  return (
    <div>
      <ul>
        {optimisticComments.map((c) => (
          <li
            key={c.id}
            style={{ opacity: c.id.startsWith("temp-") ? 0.6 : 1 }}
          >
            <strong>{c.author}</strong>: {c.text}
          </li>
        ))}
      </ul>
      {state.error && <p style={{ color: "red" }}>{state.error}</p>}
      <form action={handleSubmit}>
        <input name="text" type="text" placeholder="댓글을 입력하세요" />
        <CommentSubmitButton />
      </form>
    </div>
  );
}

flowchart TD
    A[새 폼 개발 시작] --> B{복잡도}
    B -->|단순 3~5개 필드| C[네이티브 Actions 검토]
    B -->|복잡한 다단계 폼| D[RHF 또는 TanStack Form]
    C --> E{실시간 검증 필요?}
    E -->|아니오| F[useActionState + useFormStatus]
    E -->|예| G[RHF와 useActionState 병용]
    F --> H{낙관적 UI 필요?}
    H -->|예| I[useOptimistic 추가]
    H -->|아니오| J[완성]
    I --> J
    G --> J
    D --> J