[🤖] Next.js Server Actions 실전: 에러 처리, 유효성 검사, 낙관적 UI 업데이트

Next.js Server Actions를 실무에 적용할 때 마주하는 에러 처리, 데이터 유효성 검사, 그리고 사용자 경험을 향상시키는 낙관적 UI 업데이트 기법을 상세한 코드 예시와 함께 알아보세요.

게시일: 2026-03-26

수정일: 2026-03-26

31분

단어: 3,270개

정보

🤖 이 포스팅은 Gemini 2.5 Flash AI가 작성했어요.
내용의 정확성을 위해 검토를 거쳤지만, 실무 적용 전 공식 문서를 함께 참고해 주세요.

유용한 팁

Next.js Server Actions를 활용해 안전하고 사용자 친화적인 웹 애플리케이션을 만드는 방법을 에러 처리, 유효성 검사, 낙관적 UI 업데이트 기법을 통해 상세히 알려드려요.

안녕하세요, 블루예요! 🚀 10년 넘게 풀스택 개발자로 일하면서 수많은 기술 변화를 경험해 왔는데요, 최근 프런트엔드와 백엔드의 경계를 허무는 Next.js Server Actions의 등장은 정말 흥미로운 변화라고 생각해요.

Server Actions는 단순히 서버 코드를 클라이언트 컴포넌트에서 호출하는 것을 넘어, 사용자 경험(UX)과 개발자 경험(DX)을 혁신할 잠재력을 가지고 있어요.
하지만 실무에 적용하려면 단순히 호출하는 것을 넘어, 데이터 유효성 검사, 에러 처리, 그리고 사용자에게 즉각적인 피드백을 제공하는 낙관적 UI 업데이트와 같은 고급 기법들을 잘 이해하고 적용해야 해요.

이 글에서는 Server Actions를 더욱 견고하고 사용자 친화적으로 만드는 실전 기법들을 초중급 개발자분들의 눈높이에 맞춰 상세히 알려드릴게요.

🤔 Server Actions, 왜 중요할까요?

0️⃣ 클라이언트-서버 경계를 허무는 새로운 패러다임

기존 웹 개발에서는 클라이언트(브라우저)에서 서버의 데이터를 조작하거나 특정 로직을 실행하려면 REST API나 GraphQL 같은 별도의 API 엔드포인트를 만들고, 클라이언트에서 fetch 등의 비동기 요청을 보내야 했어요.
이 과정에서 API 라우트 정의, 데이터 직렬화/역직렬화, 상태 관리 등 여러 복잡한 단계를 거쳐야 했죠.

하지만 Next.js Server Actions는 이러한 경계를 모호하게 만들어요. 클라이언트 컴포넌트나 서버 컴포넌트에서 직접 서버 코드를 호출할 수 있게 되어, 마치 로컬 함수를 호출하듯이 서버 로직을 실행할 수 있게 되었어요.
이는 개발 복잡성을 크게 줄이고, 더 빠르고 효율적인 데이터 처리 흐름을 가능하게 해요.

1️⃣ 기존 API 라우트 방식과의 차이점

Server Actions는 Next.js App Router에서 제공하는 API 라우트(Route Handlers)와 유사한 기능을 수행하지만, 몇 가지 중요한 차이점이 있어요.

정보

API 라우트 (Route Handlers): 별도의 HTTP 엔드포인트(예: /api/users)를 정의하고, 클라이언트에서 fetch 요청을 보내는 방식이에요.
주로 외부 서비스와의 연동이나 복잡한 데이터 조회 로직에 적합해요.

유용한 팁

Server Actions: 클라이언트 컴포넌트에서 직접 호출 가능한 서버 함수예요.
주로 폼 제출, 데이터 변경, 인증과 같은 특정 사용자 인터랙션에 대한 서버 로직을 처리하는 데 최적화되어 있어요.
네트워크 요청을 명시적으로 작성할 필요 없이, 함수 호출만으로 서버 코드를 실행할 수 있다는 것이 가장 큰 장점이에요.

Server Actions는 POST 요청에 최적화되어 있으며, FormData 객체를 자동으로 처리해주기 때문에 폼 제출 시 매우 편리해요. 또한, revalidatePath나 revalidateTag와 같은 Next.js의 캐싱 재검증 기능과 긴밀하게 통합되어 있어 데이터 일관성을 유지하기 쉽다는 장점도 있어요.

⚙️ Server Actions 기본 사용법

본격적으로 Server Actions를 사용하는 방법을 알아볼게요.

0️⃣ 간단한 폼 제출 예시

가장 기본적인 Server Actions는 "use server" 지시어를 파일 맨 위에 추가하거나, 함수 앞에 붙여 서버에서 실행될 함수임을 명시하는 것으로 시작해요.
주로 <form> 태그의 action 속성에 직접 연결하여 사용해요.

app/actions.ts (서버 액션 정의):

"use server"; // 이 파일의 모든 함수는 서버에서 실행됩니다.

import { revalidatePath } from "next/cache";

interface FormData {
  title: string;
  content: string;
}

export async function createPost(formData: FormData) {
  // 실제 데이터베이스 저장 로직을 여기에 구현해요.
  // 예시를 위해 간단히 콘솔에 출력하고 지연 시간을 줘봤어요.
  console.log("게시글 생성 요청:", formData);
  await new Promise((resolve) => setTimeout(resolve, 1000)); // 네트워크 지연 흉내

  // 데이터베이스에 저장했다고 가정하고, 성공 메시지를 반환해요.
  const newPost = { id: Date.now().toString(), ...formData };
  console.log("새로운 게시글 생성 완료:", newPost);

  // 캐시된 데이터를 재검증하여 UI를 업데이트해요.
  revalidatePath("/posts"); // /posts 경로의 캐시를 무효화하여 최신 데이터를 가져오게 해요.

  return { success: true, message: "게시글이 성공적으로 생성되었어요.", post: newPost };
}

app/posts/create/page.tsx (클라이언트 컴포넌트에서 폼 사용):

"use client";

import { createPost } from "@/app/actions"; // Server Action 임포트
import { useState } from "react";

export default function CreatePostPage() {
  const [message, setMessage] = useState("");

  // Server Action을 직접 호출하는 함수를 정의해요.
  const handleSubmit = async (formData: FormData) => {
    // FormData 객체는 input의 name 속성을 기반으로 자동으로 생성돼요.
    const title = formData.get("title") as string;
    const content = formData.get("content") as string;

    // Server Action을 호출해요.
    const result = await createPost({ title, content });
    setMessage(result.message);
  };

  return (
    <div className="max-w-md mx-auto p-4 bg-white shadow-md rounded-lg">
      <h1 className="text-2xl font-bold mb-4">새 게시글 작성</h1>
      {/* <form action={createPost}> 와 같이 직접 Server Action을 연결할 수도 있어요. */}
      {/* 여기서는 추가 로직 처리를 위해 handleSubmit을 사용했어요. */}
      <form action={handleSubmit}>
        <div className="mb-4">
          <label htmlFor="title" className="block text-gray-700 text-sm font-bold mb-2">
            제목
          </label>
          <input
            type="text"
            id="title"
            name="title" // name 속성이 중요해요!
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            required
          />
        </div>
        <div className="mb-6">
          <label htmlFor="content" className="block text-gray-700 text-sm font-bold mb-2">
            내용
          </label>
          <textarea
            id="content"
            name="content" // name 속성이 중요해요!
            rows={5}
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
            required
          ></textarea>
        </div>
        <button
          type="submit"
          className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline"
        >
          게시글 생성
        </button>
      </form>
      {message && <p className="mt-4 text-green-600">{message}</p>}
    </div>
  );
}

위 예시에서는 createPost Server Action을 직접 handleSubmit 함수 내에서 호출했어요. 이렇게 하면 폼 제출 전후에 추가적인 클라이언트 사이드 로직을 실행할 수 있어요.
또는 <form action={createPost}>와 같이 action 속성에 Server Action을 직접 넘겨줄 수도 있답니다.

1️⃣ useFormStatus와 useFormState 훅 활용

Next.js는 Server Actions와 함께 사용할 수 있는 두 가지 유용한 React 훅을 제공해요. 바로 useFormStatus와 useFormState예요.

useFormStatus로 로딩 상태 관리하기

useFormStatus 훅은 폼의 제출 상태(pending 여부)를 알려줘서, 폼이 제출되는 동안 버튼을 비활성화하거나 로딩 스피너를 보여주는 등의 작업을 할 수 있게 해요.
이 훅은 반드시 <form> 컴포넌트의 자식 컴포넌트에서 호출되어야 해요.

app/posts/create/page.tsx (일부 수정):

"use client";

import { createPost } from "@/app/actions";
import { useState } from "react";
+import { useFormStatus } from "react-dom"; // useFormStatus 임포트

+// 제출 버튼 컴포넌트
+function SubmitButton() {
+  const { pending } = useFormStatus(); // 폼의 제출 상태를 가져와요.
+
+  return (
+    <button
+      type="submit"
+      className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline disabled:opacity-50 disabled:cursor-not-allowed"
+      disabled={pending} // pending 상태일 때 버튼 비활성화
+    >
+      {pending ? "생성 중..." : "게시글 생성"}
+    </button>
+  );
+}

export default function CreatePostPage() {
  const [message, setMessage] = useState("");

  const handleSubmit = async (formData: FormData) => {
    const title = formData.get("title") as string;
    const content = formData.get("content") as string;

    const result = await createPost({ title, content });
    setMessage(result.message);
  };

  return (
    <div className="max-w-md mx-auto p-4 bg-white shadow-md rounded-lg">
      <h1 className="text-2xl font-bold mb-4">새 게시글 작성</h1>
      <form action={handleSubmit}>
        <div className="mb-4">
          <label htmlFor="title" className="block text-gray-700 text-sm font-bold mb-2">
            제목
          </label>
          <input
            type="text"
            id="title"
            name="title"
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            required
          />
        </div>
        <div className="mb-6">
          <label htmlFor="content" className="block text-gray-700 text-sm font-bold mb-2">
            내용
          </label>
          <textarea
            id="content"
            name="content"
            rows={5}
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
            required
          ></textarea>
        </div>
-        <button
-          type="submit"
-          className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline"
-        >
-          게시글 생성
-        </button>
+        <SubmitButton />
      </form>
      {message && <p className="mt-4 text-green-600">{message}</p>}
    </div>
  );
}

useFormState로 서버 응답 상태 관리하기

useFormState 훅은 Server Action의 이전 결과(state)와 현재 제출된 폼 데이터를 인자로 받아 새로운 상태를 반환하는 훅이에요.
이를 통해 서버 액션의 성공/실패 메시지, 유효성 검사 에러 등을 클라이언트에서 편리하게 관리할 수 있어요.

useFormState는 useReducer와 비슷한 방식으로 동작하며, 초기 상태와 Server Action 함수를 인자로 받아요.

app/posts/create/page.tsx (useFormState 적용):

"use client";

import { createPost } from "@/app/actions";
import { useState } from "react";
+import { useFormStatus, useFormState } from "react-dom"; // useFormState 임포트

// ... SubmitButton 컴포넌트는 동일해요 ...

export default function CreatePostPage() {
-  const [message, setMessage] = useState("");

-  const handleSubmit = async (formData: FormData) => {
-    const title = formData.get("title") as string;
-    const content = formData.get("content") as string;
-
-    const result = await createPost({ title, content });
-    setMessage(result.message);
-  };

+  // useFormState 훅을 사용해요. 첫 번째 인자는 Server Action, 두 번째 인자는 초기 상태예요.
+  // state는 Server Action의 반환값이에요.
+  const [state, formAction] = useFormState(createPost, {
+    success: false,
+    message: "",
+    errors: { title: "", content: "" },
+  });
+
   return (
     <div className="max-w-md mx-auto p-4 bg-white shadow-md rounded-lg">
       <h1 className="text-2xl font-bold mb-4">새 게시글 작성</h1>
-      <form action={handleSubmit}>
+      <form action={formAction}> {/* useFormState가 반환한 formAction을 사용해요. */}
         <div className="mb-4">
           <label htmlFor="title" className="block text-gray-700 text-sm font-bold mb-2">
             제목
           </label>
           <input
             type="text"
             id="title"
             name="title"
             className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
             required
           />
         </div>
         <div className="mb-6">
           <label htmlFor="content" className="block text-gray-700 text-sm font-bold mb-2">
             내용
           </label>
           <textarea
             id="content"
             name="content"
             rows={5}
             className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
             required
           ></textarea>
         </div>
         <SubmitButton />
       </form>
-      {message && <p className="mt-4 text-green-600">{message}</p>}
+      {state.message && (
+        <p className={`mt-4 ${state.success ? "text-green-600" : "text-red-600"}`}>
+          {state.message}
+        </p>
+      )}
     </div>
   );
}

이제 state.message를 통해 Server Action의 결과를 표시할 수 있게 되었어요. useFormState는 Server Action의 반환값을 클라이언트 컴포넌트에서 쉽게 접근할 수 있도록 해주는 강력한 도구예요.

🚨 안전한 Server Actions 구현하기

사용자로부터 입력받은 데이터를 서버에서 처리할 때는 항상 유효성 검사와 에러 처리를 철저히 해야 해요. 그렇지 않으면 보안 취약점이나 예기치 않은 버그로 이어질 수 있답니다.

0️⃣ 데이터 유효성 검사 (Zod 라이브러리 활용)

Server Actions는 서버에서 실행되기 때문에, 클라이언트에서 폼을 제출하기 전에 유효성 검사를 하더라도 서버에서 한 번 더 검증하는 것이 필수적이에요.
여기서는 강력하고 타입 안전한 유효성 검사 라이브러리인 Zod를 사용해볼게요.

먼저 Zod를 설치해주세요:

npm install zod
# 또는
yarn add zod
# 또는
pnpm add zod

app/actions.ts (Zod를 이용한 유효성 검사 추가):

"use server";

import { revalidatePath } from "next/cache";
+import { z } from "zod"; // Zod 임포트

+// Zod 스키마 정의: 게시글 데이터의 유효성 규칙을 정의해요.
+const postSchema = z.object({
+  title: z.string().min(5, "제목은 5자 이상이어야 해요.").max(100, "제목은 100자 이하여야 해요."),
+  content: z.string().min(10, "내용은 10자 이상이어야 해요."),
+});

-interface FormData {
-  title: string;
-  content: string;
-}
-
-export async function createPost(formData: FormData) {
+export async function createPost(prevState: any, formData: FormData) {
+  // FormData를 Zod 스키마에 맞게 파싱해요.
+  const parsed = postSchema.safeParse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  });
+
+  // 유효성 검사 실패 시 에러 반환
+  if (!parsed.success) {
+    const fieldErrors = parsed.error.flatten().fieldErrors;
+    return {
+      success: false,
+      message: "입력값이 유효하지 않아요.",
+      errors: {
+        title: fieldErrors.title?.[0] || "",
+        content: fieldErrors.content?.[0] || "",
+      },
+    };
+  }
+
+  const { title, content } = parsed.data; // 유효성 검사 통과된 데이터
+
   console.log("게시글 생성 요청:", formData);
   await new Promise((resolve) => setTimeout(resolve, 1000));

   const newPost = { id: Date.now().toString(), title, content }; // parsed.data 사용
   console.log("새로운 게시글 생성 완료:", newPost);

   revalidatePath("/posts");

-  return { success: true, message: "게시글이 성공적으로 생성되었어요.", post: newPost };
+  return { success: true, message: "게시글이 성공적으로 생성되었어요.", errors: {}, post: newPost };
}

createPost Server Action이 이제 prevState를 첫 번째 인자로 받도록 수정되었고, FormData는 두 번째 인자로 받아요. 이는 useFormState 훅의 시그니처에 맞춰진 것이에요.
Zod를 사용하여 formData의 유효성을 검사하고, 유효하지 않은 경우 에러 메시지와 함께 실패 상태를 반환하도록 했어요.

app/posts/create/page.tsx (유효성 검사 에러 메시지 표시):

"use client";

import { createPost } from "@/app/actions";
import { useState } from "react";
import { useFormStatus, useFormState } from "react-dom";

interface FormState {
  success: boolean;
  message: string;
  errors: { title: string; content: string };
}

// ... SubmitButton 컴포넌트는 동일해요 ...

export default function CreatePostPage() {
  const [state, formAction] = useFormState<FormState, FormData>(createPost, {
    success: false,
    message: "",
    errors: { title: "", content: "" },
  });

  return (
    <div className="max-w-md mx-auto p-4 bg-white shadow-md rounded-lg">
      <h1 className="text-2xl font-bold mb-4">새 게시글 작성</h1>
      <form action={formAction}>
        <div className="mb-4">
          <label htmlFor="title" className="block text-gray-700 text-sm font-bold mb-2">
            제목
          </label>
          <input
            type="text"
            id="title"
            name="title"
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            required
          />
+          {state.errors.title && <p className="text-red-500 text-xs mt-1">{state.errors.title}</p>}
         </div>
         <div className="mb-6">
           <label htmlFor="content" className="block text-gray-700 text-sm font-bold mb-2">
             내용
           </label>
           <textarea
             id="content"
             name="content"
             rows={5}
             className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight focus:outline-none focus:shadow-outline"
             required
           ></textarea>
+          {state.errors.content && <p className="text-red-500 text-xs mt-1">{state.errors.content}</p>}
         </div>
         <SubmitButton />
       </form>
       {state.message && (
         <p className={`mt-4 ${state.success ? "text-green-600" : "text-red-600"}`}>
           {state.message}
         </p>
       )}
     </div>
   );
}

이제 폼 필드 아래에 유효성 검사 에러 메시지가 표시되는 것을 확인할 수 있어요.

1️⃣ 에러 처리 전략 (try-catch, useFormState 에러 상태)

Server Actions 내에서 예상치 못한 에러가 발생했을 때도 사용자에게 적절한 피드백을 제공하고, 애플리케이션이 멈추지 않도록 해야 해요.
Server Actions는 일반적인 비동기 함수처럼 try-catch 블록을 사용하여 에러를 처리할 수 있어요.

app/actions.ts (에러 처리 추가):

"use server";

import { revalidatePath } from "next/cache";
import { z } from "zod";

const postSchema = z.object({
  title: z.string().min(5, "제목은 5자 이상이어야 해요.").max(100, "제목은 100자 이하여야 해요."),
  content: z.string().min(10, "내용은 10자 이상이어야 해요."),
});

export async function createPost(prevState: any, formData: FormData) {
  const parsed = postSchema.safeParse({
    title: formData.get("title"),
    content: formData.get("content"),
  });

  if (!parsed.success) {
    const fieldErrors = parsed.error.flatten().fieldErrors;
    return {
      success: false,
      message: "입력값이 유효하지 않아요.",
      errors: {
        title: fieldErrors.title?.[0] || "",
        content: fieldErrors.content?.[0] || "",
      },
    };
  }

  const { title, content } = parsed.data;

+  try {
     console.log("게시글 생성 요청:", formData);
     await new Promise((resolve) => setTimeout(resolve, 1000));

     // 의도적으로 에러를 발생시켜 테스트해볼 수 있어요.
     // if (title === "에러") throw new Error("의도된 서버 에러 발생!");

     const newPost = { id: Date.now().toString(), title, content };
     console.log("새로운 게시글 생성 완료:", newPost);

     revalidatePath("/posts");

     return { success: true, message: "게시글이 성공적으로 생성되었어요.", errors: {}, post: newPost };
+  } catch (error: any) {
+    console.error("게시글 생성 중 서버 에러 발생:", error);
+    return {
+      success: false,
+      message: `서버 에러가 발생했어요: ${error.message || "알 수 없는 에러"}`,
+      errors: { title: "", content: "" },
+    };
+  }
}

이제 Server Action 내에서 에러가 발생하면 catch 블록에서 이를 잡아서 useFormState로 에러 메시지를 클라이언트에 전달할 수 있게 되었어요.

🚀 사용자 경험을 위한 낙관적 UI 업데이트

Server Actions는 비동기적으로 동작하기 때문에, 서버에서 작업이 완료될 때까지 약간의 지연이 발생할 수 있어요. 이 시간 동안 사용자에게 아무런 피드백이 없다면 답답함을 느낄 수 있죠.
이때 낙관적 UI 업데이트(Optimistic UI Update) 기법을 사용하면 사용자 경험을 크게 향상시킬 수 있어요.

0️⃣ 낙관적 업데이트란?

낙관적 업데이트는 서버 요청이 성공할 것이라고 '낙관적으로' 가정하고, 서버 응답을 기다리지 않고 즉시 UI를 업데이트하는 기법이에요.
만약 서버 요청이 실패하면, 업데이트했던 UI를 이전 상태로 되돌려(롤백) 주면 돼요.

이를 통해 사용자는 마치 즉시 작업이 완료된 것처럼 느끼게 되어, 애플리케이션이 더 빠르고 반응성이 좋다고 인식하게 돼요.

1️⃣ useOptimistic 훅 활용 예시

React 18부터 제공되는 useOptimistic 훅은 이러한 낙관적 UI 업데이트를 쉽게 구현할 수 있도록 도와줘요.
이 훅은 현재 상태(state)와 낙관적 상태(optimisticState) 두 가지를 관리해요. 서버 작업이 진행되는 동안 낙관적 상태를 보여주다가, 서버 응답이 오면 실제 상태로 전환하는 방식이죠.

간단한 댓글 추가 기능을 예시로 useOptimistic을 사용해볼게요.

app/comments/actions.ts (댓글 추가 Server Action):

"use server";

import { revalidatePath } from "next/cache";
import { z } from "zod";

const commentSchema = z.object({
  postId: z.string(),
  content: z.string().min(1, "댓글 내용은 비워둘 수 없어요.").max(200, "댓글은 200자 이하여야 해요."),
});

interface Comment {
  id: string;
  postId: string;
  content: string;
  isOptimistic?: boolean; // 낙관적 업데이트 여부를 표시
}

// 임시 댓글 저장소 (실제로는 DB를 사용해요)
const comments: Comment[] = [];

export async function addComment(prevState: any, formData: FormData) {
  const parsed = commentSchema.safeParse({
    postId: formData.get("postId"),
    content: formData.get("content"),
  });

  if (!parsed.success) {
    return { success: false, message: parsed.error.flatten().fieldErrors.content?.[0] || "", comment: null };
  }

  const { postId, content } = parsed.data;

  try {
    console.log(`[Server Action] 댓글 추가 요청: postId=${postId}, content=${content}`);
    await new Promise((resolve) => setTimeout(resolve, 1500)); // 의도적인 지연

    const newComment: Comment = { id: Date.now().toString(), postId, content };
    comments.push(newComment); // 댓글 저장
    console.log("[Server Action] 댓글 추가 완료:", newComment);

    revalidatePath(`/posts/${postId}`); // 해당 게시글의 캐시 재검증

    return { success: true, message: "댓글이 성공적으로 추가되었어요.", comment: newComment };
  } catch (error: any) {
    console.error("[Server Action] 댓글 추가 중 에러 발생:", error);
    return { success: false, message: `댓글 추가 실패: ${error.message || "알 수 없는 에러"}`, comment: null };
  }
}

app/posts/[id]/page.tsx (댓글 목록 및 추가 폼 - 클라이언트 컴포넌트):

"use client";

import { addComment } from "@/app/comments/actions";
import { useState, useRef, useOptimistic } from "react";
import { useFormStatus, useFormState } from "react-dom";

interface Comment {
  id: string;
  postId: string;
  content: string;
  isOptimistic?: boolean;
}

interface FormState {
  success: boolean;
  message: string;
  comment: Comment | null;
}

// 임시 데이터 (실제로는 DB에서 가져와야 해요)
const initialComments: Comment[] = [
  { id: "1", postId: "post-1", content: "첫 번째 댓글이에요!" },
  { id: "2", postId: "post-1", content: "정말 유익한 글이네요." },
];

// 댓글 제출 버튼 컴포넌트
function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button
      type="submit"
      className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded focus:outline-none focus:shadow-outline disabled:opacity-50 disabled:cursor-not-allowed"
      disabled={pending}
    >
      {pending ? "추가 중..." : "댓글 추가"}
    </button>
  );
}

export default function PostDetailPage({ params }: { params: { id: string } }) {
  const postId = params.id;
  const formRef = useRef<HTMLFormElement>(null);

  // useOptimistic 훅을 사용해요. 첫 번째 인자는 실제 상태, 두 번째 인자는 낙관적 업데이트 함수예요.
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    initialComments, // 초기 댓글 목록
    (currentComments: Comment[], newCommentContent: string) => [
      ...currentComments,
      { id: "temp-id-" + Date.now(), postId, content: newCommentContent, isOptimistic: true }, // 낙관적 댓글 추가
    ]
  );

  const [state, formAction] = useFormState<FormState, FormData>(addComment, {
    success: false,
    message: "",
    comment: null,
  });

  const handleFormAction = async (formData: FormData) => {
    const commentContent = formData.get("content") as string;

    // 낙관적 업데이트를 먼저 적용해요.
    addOptimisticComment(commentContent);

    // 실제 Server Action을 호출해요.
    const result = await formAction(formData);

    // Server Action이 실패하면 (예: 유효성 검사 실패) UI를 롤백하거나 에러 메시지를 표시해요.
    if (!result.success) {
      console.error("댓글 추가 실패:", result.message);
      // 여기서는 롤백 로직을 직접 구현하지 않고, 메시지로만 피드백을 줘요.
      // 실제 앱에서는 `optimisticComments`에서 해당 임시 항목을 제거하는 로직이 필요할 수 있어요.
    } else {
      // 성공하면 폼 초기화
      formRef.current?.reset();
    }
  };

  return (
    <div className="max-w-xl mx-auto p-6 bg-white shadow-md rounded-lg mt-8">
      <h1 className="text-3xl font-bold mb-6">게시글 상세 페이지 ({postId})</h1>

      <div className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">댓글 목록</h2>
        {
          optimisticComments.length === 0 ? (
            <p className="text-gray-500">아직 댓글이 없어요.</p>
          ) : (
            <ul>
              {optimisticComments.map((comment) => (
                <li
                  key={comment.id}
                  className={`border-b border-gray-200 py-2 ${comment.isOptimistic ? "opacity-60 text-gray-500 italic" : ""}`}
                >
                  {comment.content}
                  {comment.isOptimistic && <span className="ml-2 text-sm"> (전송 중...)</span>}
                </li>
              ))}
            </ul>
          )
        }
      </div>

      <div className="mb-4">
        <h2 className="text-2xl font-semibold mb-4">댓글 작성</h2>
        <form ref={formRef} action={handleFormAction} className="flex flex-col gap-4">
          <input type="hidden" name="postId" value={postId} />
          <textarea
            name="content"
            rows={3}
            placeholder="댓글을 입력해주세요."
            className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            required
          ></textarea>
          {state.message && <p className="text-red-500 text-sm">{state.message}</p>}
          <SubmitButton />
        </form>
      </div>
    </div>
  );
}

위 예시에서 addOptimisticComment 함수를 통해 optimisticComments 상태를 즉시 업데이트하여 새로운 댓글이 UI에 바로 보이도록 했어요.
실제 서버 응답이 오기 전까지는 isOptimistic 플래그를 이용해 약간 흐리게 표시하여 '전송 중'임을 사용자에게 알릴 수 있어요.
만약 Server Action이 실패하면 state.message를 통해 에러를 표시하고, 필요하다면 낙관적으로 추가했던 항목을 제거하는 롤백 로직을 추가할 수 있어요.

📝 정리하며

지금까지 Next.js Server Actions를 실무에 적용할 때 필요한 핵심 기법들을 함께 살펴보았어요. Server Actions는 서버와 클라이언트 간의 데이터 흐름을 단순화하고 개발 생산성을 높이는 강력한 도구이지만, 그만큼 주의 깊은 설계와 구현이 필요해요.

0️⃣ 핵심 요약

• Server Actions: 클라이언트 컴포넌트에서 직접 서버 코드를 호출할 수 있게 하여 개발 복잡성을 줄이고 효율적인 데이터 처리를 가능하게 해요.
  
• useFormStatus: 폼 제출 시 로딩 상태를 관리하여 사용자에게 즉각적인 피드백을 제공해요.
  
• useFormState: Server Action의 반환값을 클라이언트 컴포넌트에서 쉽게 접근하고, 유효성 검사 에러나 서버 응답 메시지를 표시하는 데 유용해요.
  
• 데이터 유효성 검사: Zod와 같은 라이브러리를 사용하여 서버에서 입력값의 유효성을 철저히 검증하는 것이 필수적이에요.
  
• 에러 처리: try-catch 블록을 통해 Server Actions 내부의 예외를 처리하고, useFormState를 통해 사용자에게 의미 있는 에러 메시지를 전달해야 해요.
  
• 낙관적 UI 업데이트: useOptimistic 훅을 활용하여 서버 응답을 기다리지 않고 UI를 즉시 업데이트함으로써 사용자 경험을 크게 향상시킬 수 있어요.

1️⃣ 다음 액션

Server Actions는 Next.js 개발의 미래를 이끌 중요한 기술 중 하나예요. 이 글에서 다룬 내용들을 바탕으로 실제 프로젝트에 적용해보시면서, Server Actions의 강력함을 직접 경험해보시길 추천해요.
특히, 데이터 유효성 검사와 에러 처리는 사용자에게 신뢰성 있는 서비스를 제공하기 위한 필수 요소이니, 반드시 습관화해주시길 바라요.

궁금한 점이나 더 깊이 논의하고 싶은 부분이 있다면 언제든지 댓글로 남겨주세요! 다음에는 더 유익한 주제로 찾아올게요.

📮 참고

• Next.js Docs: Server Actions and Mutations
• React Docs: useFormStatus
• React Docs: useFormState
• React Docs: useOptimistic
• Zod Documentation

• Next.js
• Server Actions
• React
• Form Handling
• Error Handling
• Optimistic UI
• Validation
• App Router
• ai

박상은

아무것도 하지 않을 거면 죽어버려.

연관된 포스트

2026-03-29

단어: 1,470개

17분

[🤖] Next.js App Router 프로젝트를 위한 GitHub Actions CI/CD 구축 가이드

Next.js App Router 기반 프로젝트의 배포 과정을 자동화하는 GitHub Actions CI/CD 워크플로우를 단계별로 구축하고 최적화하는 방법을 상세히 알려드려요.

• Next.js
• GitHub Actions
• CI/CD
• 배포 자동화
• 프론트엔드
• ai

---



2026-03-28

단어: 2,004개

24분

[🤖] Turborepo로 Next.js 모노레포 구축: 효율적인 개발 및 최적화 전략

Turborepo를 활용하여 Next.js 프로젝트를 모노레포로 구성하고, 공유 컴포넌트, 유틸리티, CI/CD 최적화 방안을 실무 예시와 함께 자세히 설명해 드려요.

• Turborepo
• Next.js
• 모노레포
• Monorepo
• 개발환경
• 성능최적화
• CI/CD
• ai

---



2026-03-27

단어: 2,318개

27분

[🤖] React useEffect 훅, 이제 헷갈리지 마세요! (의존성 배열, 클린업 완벽 가이드)

React 개발에서 필수적인 useEffect 훅의 동작 원리부터 의존성 배열, 클린업 함수 활용법, 그리고 실무에서 자주 겪는 실수와 최적화 전략까지, 초중급 개발자를 위한 완벽 가이드를 제공해요.

• React
• useEffect
• React Hooks
• JavaScript
• 웹 개발
• 최적화
• ai

---



2026-03-25

단어: 1,981개

21분

[🤖] TypeScript 유틸리티 타입 완벽 가이드: 실전 활용 패턴

TypeScript 유틸리티 타입의 핵심 개념과 실전 활용법을 깊이 있게 다뤄요. Pick, Omit, Partial, Required 등 자주 쓰는 유틸리티 타입으로 복잡한 타입을 효과적으로 다루는 방법을 배워보세요. 타입스크립트 코드의 재사용성과 안정성을 높이는 노하우를 공유해요.

• typescript
• utility types
• 제네릭
• 타입스크립트
• 프론트엔드
• 백엔드
• 개발
• ai

---



2026-03-24

단어: 1,707개

20분

[🤖] Next.js App Router 미들웨어: 강력한 요청 처리 전략과 실전 예제

Next.js App Router 환경에서 미들웨어를 활용해 사용자 인증, 리다이렉션, 국제화 등의 요청 처리 로직을 효율적으로 구현하는 방법을 실전 예제와 함께 자세히 알아보세요.

• Next.js
• Middleware
• App Router
• 인증
• 리다이렉션
• 국제화
• 웹 개발
• ai

---



2026-03-23

단어: 1,625개

19분

[🤖] 타입스크립트 제네릭 심화: 실용적인 패턴과 흔한 오해들

타입스크립트 제네릭(Generics)을 깊이 이해하고, 실무에서 자주 사용되는 제네릭 패턴과 흔히 겪는 오해들을 실제 코드 예시와 함께 쉽고 명확하게 설명해 드려요. 타입 안정성과 코드 재사용성을 높이는 방법을 배워보세요.

• TypeScript
• Generics
• 타입스크립트
• 타입 안정성
• 코드 재사용성
• ai

---



2026-03-22

단어: 1,846개

18분

[🤖] Next.js Route Handler: App Router에서 안전하고 효율적인 API 구축하기 (인증, 에러 처리 포함)

Next.js App Router의 Route Handler를 사용하여 API 엔드포인트를 구축하는 방법을 자세히 알아봐요. 인증, 에러 처리, 그리고 캐싱 전략을 포함한 실용적인 팁으로 안전하고 효율적인 서버리스 함수를 만드는 방법을 익혀봐요.

• Next.js
• Route Handler
• App Router
• API
• 인증
• 에러 처리
• 서버리스
• ai

---



2026-03-21

단어: 1,932개

22분

[🤖] Next.js Image 컴포넌트 최적화: Core Web Vitals 개선부터 실전 활용까지

Next.js의 Image 컴포넌트를 활용하여 웹 성능 핵심 지표인 Core Web Vitals를 개선하고, 다양한 최적화 옵션을 실전 프로젝트에 적용하는 방법을 블루가 자세히 알려드려요.

• Next.js
• Image Optimization
• Core Web Vitals
• 웹 성능
• 프론트엔드
• ai

---



2026-03-20

단어: 2,173개

25분

[🤖] Next.js 14.1+의 혁신: Partial Prerendering (PPR) 완벽 가이드와 실전 최적화 전략

Next.js 14.1부터 도입된 Partial Prerendering (PPR)을 통해 초기 로딩 속도를 극대화하고 동적 콘텐츠를 효율적으로 처리하는 방법을 심도 있게 다루어요. PPR의 동작 원리부터 실제 프로젝트 적용 전략까지, 개발자들이 궁금해하는 모든 것을 알려드려요.

• Next.js
• PPR
• Partial Prerendering
• 웹 성능 최적화
• App Router
• ai

---



2026-03-18

단어: 1,786개

19분

[🤖] TypeScript 조건부 타입과 infer 키워드: 복잡한 타입도 손쉽게 다루는 방법

TypeScript 개발에서 마주하는 복잡한 타입 추론 문제, 조건부 타입과 infer 키워드를 활용하면 훨씬 우아하고 강력하게 해결할 수 있어요. 실전 예제와 함께 그 활용법을 심도 있게 다뤄봅니다.

• TypeScript
• 타입스크립트
• 조건부타입
• infer
• 제네릭
• 유틸리티타입
• 프론트엔드
• ai

---



2026-03-19

단어: 1,697개

21분

[🤖] JavaScript 이벤트 루프(Event Loop) 완전 정복: 비동기 처리와 런타임 동작 원리

JavaScript의 핵심 비동기 처리 메커니즘인 이벤트 루프의 동작 원리를 심도 있게 파헤쳐 봐요. 콜 스택, 태스크 큐, 마이크로태스크 큐와의 상호작용을 이해하고, 실무에서 마주치는 비동기 코드의 동작을 명확히 예측하는 방법을 알려드려요.

• JavaScript
• 이벤트루프
• 비동기
• Async
• EventLoop
• Frontend
• 성능최적화
• ai

---



2026-03-17

단어: 1,960개

23분

[🤖] Next.js Server & Client Components, 실전에서 현명하게 선택하는 가이드

Next.js App Router에서 Server Components와 Client Components 중 어떤 것을 사용해야 할지 고민이신가요? 이 글에서 두 컴포넌트의 핵심 차이점, 사용 시점, 그리고 성능 최적화를 위한 실전 전략을 블루가 알려드릴게요.

• nextjs
• server-components
• client-components
• app-router
• react
• 성능최적화
• ai

---



2026-03-17

단어: 1,878개

21분

[🤖] TypeScript satisfies 연산자: 타입 추론과 안정성을 동시에 잡는 비법

TypeScript의 `satisfies` 연산자를 활용하여 타입 추론의 유연성을 유지하면서도 엄격한 타입 안정성을 확보하는 방법을 알아보세요. 실용적인 예시를 통해 실제 프로젝트에 적용하는 노하우를 공유합니다.

• TypeScript
• satisfies
• 타입스크립트
• 타입 추론
• 타입 안정성
• 프론트엔드 개발

---



2026-03-17

단어: 1,207개

15분

[🤖] React 19 새로운 기능: use 훅, Actions, 그리고 컴파일러 미리보기

React 19의 핵심 변경 사항인 use 훅, 서버 액션, 그리고 React 컴파일러의 도입 배경과 실제 활용 예시를 초중급 개발자 눈높이에 맞춰 자세히 설명합니다. 최신 React 업데이트를 통해 애플리케이션 성능과 개발 경험을 향상시키는 방법을 알아보세요.

• React 19
• React use hook
• React Actions
• React Compiler
• 프론트엔드 최적화
• 웹 개발
• 새로운 기능
• Hooks

---



2026-03-16

단어: 1,512개

16분

[🤖] Next.js App Router 캐싱 전략: 데이터 재검증 (revalidatePath, revalidateTag) 완벽 가이드

Next.js 14 App Router에서 효율적인 데이터 캐싱 전략과 revalidatePath, revalidateTag를 이용한 데이터 재검증 방법을 실무 예시와 함께 자세히 알아보고 웹 성능을 최적화하는 방법을 배워보세요.

• Next.js
• App Router
• 캐싱
• 데이터 재검증
• revalidatePath
• revalidateTag
• 웹 성능 최적화
• Server Components