React Hook Form × Next.js Server Actions 実践ガイド【2026年最新】— useActionState・二重検証・プログレッシブ・エンハンスメント

// lib/schemas/contact.ts —— クライアント／サーバー共有の単一の正
import * as z from "zod";

export const contactSchema = z.object({
  email: z.email({ error: "メールアドレスを正しく入力してください" }),
  message: z.string().min(10, { error: "10文字以上で入力してください" }).max(2000),
  // 二重送信対策の冪等キー（クライアント生成・UUID）
  idempotencyKey: z.uuid(),
});
export type Contact = z.infer<typeof contactSchema>;

// app/contact/actions.ts
"use server";
import * as z from "zod";
import { contactSchema, type Contact } from "@/lib/schemas/contact";
import { auth } from "@/lib/auth";
import { rateLimit } from "@/lib/rate-limit";

// 返り値は判別可能ユニオン。クライアントはこれを型として受け取れる
type SubmitResult =
  | { ok: true }
  | { ok: false; formError?: string; fieldErrors?: Partial<Record<keyof Contact, string>> };

export async function submitContact(input: unknown): Promise<SubmitResult> {
  // 1) 認可：誰がこの操作をしてよいか（Server Action は公開エンドポイント）
  const session = await auth();
  if (!session) return { ok: false, formError: "ログインが必要です" };

  // 2) レート制限：濫用・スパムを止める
  const allowed = await rateLimit(`contact:${session.userId}`);
  if (!allowed) return { ok: false, formError: "時間をおいて再度お試しください" };

  // 3) 検証：信頼境界。input は unknown として必ず parse する
  const parsed = contactSchema.safeParse(input);
  if (!parsed.success) {
    const { fieldErrors } = z.flattenError(parsed.error);
    return {
      ok: false,
      // 各フィールドの先頭メッセージだけ返す
      fieldErrors: Object.fromEntries(
        Object.entries(fieldErrors).map(([k, v]) => [k, v?.[0]]),
      ) as SubmitResult["fieldErrors"],
    };
  }

  // 4) 冪等性：同じ idempotencyKey の重複実行を弾く
  const created = await db.contacts.insertIfAbsent(parsed.data); // key 重複なら no-op
  if (!created) return { ok: true }; // 既に処理済み＝成功扱い（リトライを正常系に）

  return { ok: true };
}

"use client";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { contactSchema, type Contact } from "@/lib/schemas/contact";
import { submitContact } from "./actions";

export function ContactForm() {
  const {
    register,
    handleSubmit,
    setError,
    reset,
    formState: { errors, isSubmitting, isSubmitSuccessful },
  } = useForm<Contact>({
    resolver: zodResolver(contactSchema),
    defaultValues: { email: "", message: "", idempotencyKey: crypto.randomUUID() },
  });

  const onValid = async (data: Contact) => {
    const res = await submitContact(data); // Server Action を RPC として呼ぶ
    if (res.ok) {
      reset({ email: "", message: "", idempotencyKey: crypto.randomUUID() }); // 次回用に新キー
      return;
    }
    // サーバーの項目別エラーを該当フィールドへ
    for (const [name, message] of Object.entries(res.fieldErrors ?? {})) {
      if (message) setError(name as keyof Contact, { message });
    }
    // 全体エラーは root.server へ
    if (res.formError) setError("root.server", { message: res.formError });
  };

  return (
    <form onSubmit={handleSubmit(onValid)} noValidate className="space-y-4">
      <div>
        <label htmlFor="email">メールアドレス</label>
        <input
          id="email"
          type="email"
          {...register("email")}
          aria-invalid={errors.email ? "true" : "false"}
          aria-describedby={errors.email ? "email-error" : undefined}
        />
        {errors.email && <p id="email-error" role="alert">{errors.email.message}</p>}
      </div>

      <div>
        <label htmlFor="message">お問い合わせ</label>
        <textarea
          id="message"
          {...register("message")}
          aria-invalid={errors.message ? "true" : "false"}
          aria-describedby={errors.message ? "message-error" : undefined}
        />
        {errors.message && <p id="message-error" role="alert">{errors.message.message}</p>}
      </div>

      {errors.root?.server && <p role="alert">{errors.root.server.message}</p>}
      {isSubmitSuccessful && <p role="status">送信しました。ありがとうございます。</p>}

      {/* 送信中は無効化＝二重送信を構造的に防ぐ */}
      <button disabled={isSubmitting}>{isSubmitting ? "送信中…" : "送信"}</button>
    </form>
  );
}

// app/contact/actions.ts（progressive 版）
"use server";
import * as z from "zod";
import { contactSchema } from "@/lib/schemas/contact";

export type FormState = {
  ok: boolean;
  formError?: string;
  fieldErrors?: Record<string, string[] | undefined>;
};

export async function contactAction(_prev: FormState, formData: FormData): Promise<FormState> {
  // FormData → オブジェクト化して Zod で検証（サーバーが唯一の検証者）
  const parsed = contactSchema.safeParse({
    email: formData.get("email"),
    message: formData.get("message"),
    idempotencyKey: formData.get("idempotencyKey"),
  });
  if (!parsed.success) {
    return { ok: false, fieldErrors: z.flattenError(parsed.error).fieldErrors };
  }
  await db.contacts.insertIfAbsent(parsed.data);
  return { ok: true };
}

"use client";
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
import { contactAction, type FormState } from "./actions";

const initial: FormState = { ok: false };

function SubmitButton() {
  const { pending } = useFormStatus(); // form 内の子で pending を取る
  return <button disabled={pending}>{pending ? "送信中…" : "送信"}</button>;
}

export function ContactForm() {
  const [state, formAction] = useActionState(contactAction, initial);
  return (
    <form action={formAction} noValidate className="space-y-4">
      <label htmlFor="email">メールアドレス</label>
      <input id="email" name="email" type="email" required aria-invalid={!!state.fieldErrors?.email} />
      {state.fieldErrors?.email && <p role="alert">{state.fieldErrors.email[0]}</p>}

      <label htmlFor="message">お問い合わせ</label>
      <textarea id="message" name="message" required minLength={10} />
      {state.fieldErrors?.message && <p role="alert">{state.fieldErrors.message[0]}</p>}

      <input type="hidden" name="idempotencyKey" value={crypto.randomUUID()} />
      {state.ok && <p role="status">送信しました。</p>}
      <SubmitButton />
    </form>
  );
}

// actions.test.ts —— 信頼境界そのものをテストする
import { describe, it, expect } from "vitest";
import { submitContact } from "./actions";

it("不正な入力は fieldErrors を返し DB に触れない", async () => {
  const res = await submitContact({ email: "bad", message: "短い", idempotencyKey: "x" });
  expect(res.ok).toBe(false);
  if (!res.ok) expect(res.fieldErrors?.email).toBeTruthy();
});