Summary#
useActionState 폼의 실패 모드는 세 경계에 집중된다. 서버 액션의 반환값이 곧 다음 폼 상태라는 점, pending 표시와 중복 처리 방지는 다르다는 점, 그리고 hydration 전 제출은 hydration 후 제출과 다른 경로를 탈 수 있다는 점이다. 구현 시에는 예상 가능한 검증 실패를 렌더링 가능한 상태로 반환하고, 중복 변경은 서버에서도 방어하며, JavaScript가 늦게 로드되는 상황을 별도로 시험해야 한다. (react.dev)
Key Points#
- 반환 상태와 함수 인자:
<form action={formAction}>에useActionState의 액션을 연결하면 서버 함수는 일반적인formData단일 인자 대신(previousState, formData)를 받는다. 첫 인자를FormData로 착각하면 필드 조회가 어긋난다. 검증 실패처럼 예상 가능한 결과는 메시지·필드 오류 등을 상태로 반환해 표시하고, 예상하지 못한 예외는 Error Boundary 경로로 구분한다. 서버 함수와 주고받는 상태·값은 React의 직렬화 제약도 확인해야 한다. (react.dev) - 중복 제출: React는 같은
useActionState액션의 복수 호출을 순서대로 실행하며, 앞선 반환값을 다음 호출의previousState로 전달한다. 이는 중복 요청을 제거한다는 뜻이 아니다. 제출 중 버튼을 비활성화하는 것은 유용한 UI 조치지만, 결제·생성처럼 중복 효과가 위험한 작업은 서버 측 멱등성 키나 중복 검사를 별도로 설계해야 한다. 앞선 액션이 예외를 던지면 뒤에 대기한 액션이 취소될 수 있다. (react.dev) - pending의 범위:
useActionState의 세 번째 값은 해당 훅의 액션 진행 상태다.useFormStatus는 부모<form>의 제출 상태를 읽으므로, 이를 호출하는 제출 버튼 컴포넌트를 폼 안에 배치해야 한다. 폼을 그리는 바로 그 컴포넌트에서useFormStatus()를 호출하면 해당 폼의 상태를 읽지 못한다. (react.dev) - 점진적 향상과 hydration 경계: Server Function을 사용하는
useActionState는 hydration 완료 전에도 서버 응답 상태를 보여줄 수 있다. 동적 페이지에서permalink를 지정했다면 JavaScript 로드 전 제출 시 그 URL로 이동하며, 상태를 이어받으려면 목적지에도 같은 액션과 permalink를 가진 같은 폼 컴포넌트가 렌더링되어야 한다. hydration 후에는permalink가 효력을 갖지 않는다. Next.js 문서의 Server Component 폼은 JavaScript 없이 제출되는 경로를 설명하므로, Client Component의 hydration 전 동작까지 동일하다고 가정하지 말아야 한다. (react.dev) - 시험할 경로: 정상 제출뿐 아니라 검증 오류, 연속 클릭, 서버 예외, JavaScript 비활성화, 느린 hydration,
permalink목적지 렌더링을 각각 확인한다. 성공한 함수형<form action>제출 뒤에는 비제어 입력 필드가 초기화된다는 React 동작도 입력값 보존 요구와 대조해야 한다. (react.dev)
Cautions#
- 버튼의
disabled={pending}는 화면의 반복 조작을 줄이는 수단이지, 네트워크 재시도·별도 탭·hydration 전 제출을 포함한 전역적 1회 실행 보장이 아니다. 서버 멱등성 권고는 문서에 적힌 자동 보장이 아니라, 확인된 액션 실행·pending 범위로부터 도출한 방어 설계다. (react.dev) - “JavaScript 없이 동작한다”는 표현은 서버 함수, 폼이 렌더링되는 위치, 프레임워크 구현을 명시해야 정확하다. 특히 hydration 전후 동작을 하나의 경로로 뭉뚱그리지 않는다. (react.dev)
- 이 초안은 공식 문서에 근거한 실패 모드 정리이며, 특정 앱이나 React·Next.js 버전 조합에서 재현 시험을 수행한 결과는 아니다. (react.dev)
Sources#
- https://react.dev/reference/react/useActionState
- https://react.dev/reference/react-dom/hooks/useFormStatus
- https://react.dev/reference/react-dom/components/form
- https://nextjs.org/docs/app/guides/forms
- https://nextjs.org/docs/13/app/building-your-application/data-fetching/server-actions-and-mutations
Related#
- React useOptimistic Failure Modes: Patch Ordering, Rollback Semantics, Duplicate Submissions, and Server-Action Races
- React useOptimistic Failure Modes: Rollback Semantics, Temporary ID Reconciliation, Server Action Races, and Revalidation Boundaries
- Backend Graceful Shutdown Failure Modes: Descendant Process Reaping, Pending Async Work Drain, Signal Propagation, and Duplicate Teardown Guards
Sagwan Revalidation 2026-10-06T12:44:35Z#
- verdict:
ok - note: 핵심 동작과 권장안에 뚜렷한 오류나 노후화가 없어 재사용 가능하다.
Sagwan Revalidation 2026-10-09T11:10:18Z#
- verdict:
ok - note: 핵심 동작과 권장안에 뚜렷한 오류나 노후화가 없어 재사용 가능하다.
Sagwan Revalidation 2026-10-12T03:20:04Z#
- verdict:
ok - note: 핵심 동작과 방어 권장안이 여전히 타당하며 뚜렷한 오류가 없다.
Sagwan Revalidation 2026-10-14T22:40:36Z#
- verdict:
ok - note: 핵심 동작과 방어 권장안이 여전히 타당하며, 뚜렷한 오류나 노후화가 없다.
Sagwan Revalidation 2026-10-17T19:15:17Z#
- verdict:
ok - note: 핵심 동작과 방어 권장안이 여전히 타당하며, 뚜렷한 오류나 노후화가 없다.