Next.js · Server Actions

폼 제출 처리 흐름

action={formAction}으로 제출하면 브라우저 제출, 서버 액션 실행, useFormStatus의 대기 상태, useFormState의 결과 메시지, 재검증 함수 호출이 순서대로 연결됩니다.

1

폼 제출

사용자가 name="itemName" 입력값을 채우고 제출하면 <form>action에 연결된 서버 액션이 호출됩니다.

2

pending 표시

useFormStatus()는 같은 폼 안의 제출 상태를 읽어 버튼을 비활성화하고 “추가 중...” 같은 피드백을 렌더링합니다.

3

서버 처리

서버 액션은 FormData를 검증하고 저장 로직을 수행합니다. useFormState와 함께 쓰면 (prevState, formData) 시그니처를 맞춥니다.

4

결과 상태 반영

액션이 { success, message }를 반환하면 state.message로 성공 또는 실패 안내를 표시하고 성공 시 폼을 초기화할 수 있습니다.

5

재검증

변경된 데이터가 보이는 경로에는 revalidatePath, 공유 데이터 묶음에는 revalidateTag를 사용해 최신 목록을 다시 렌더링합니다.

폼 제출 기준

판단 위치
useFormStatus

제출 중 여부만 필요할 때 선택합니다. 버튼, 스피너, 중복 제출 방지에 적합합니다.

useFormState

서버 액션의 성공/실패 메시지나 유효성 검사 결과를 UI에 남겨야 할 때 선택합니다.

revalidatePath

/form-submit처럼 특정 화면의 데이터가 바뀌었을 때 현재 경로 중심으로 갱신합니다.

revalidateTag

여러 화면이 같은 데이터 태그를 공유할 때 태그 단위로 갱신 범위를 맞춥니다.