Supabase × Next.js App Router：API RoutesとServer Actionsをどう使い分ける？ベストプラクティスを実例付きで解説！

※ChatGPTとAPi routesとServer actionsについての使い分けをするために会話した内容をまとめたものです。

🧭 Supabase × Next.js App Router：API RoutesとServer Actionsの使い分けガイド

Next.js（App Router）では Server Actions という便利な機能が登場しました。
しかし、「Supabaseと一緒に使うとき、API Routes と Server Actions をどう使い分ければいいの？」と迷う方も多いはず。

この記事では、実際にSupabaseを使った具体例を通じて、両者の違いと使い分け方をわかりやすく解説します！

---

✅ 一言でまとめると？

フォームやUIから直接処理したい → Server Actions
fetchや外部サービス（Webhook）から呼ばれる処理 → API Routes

---

📌 API Routes と Server Actions の違いまとめ

用途・状況	Server Actions	API Routes
UIのフォーム送信	✅	❌
クライアントJSからfetchしたい	❌	✅
外部サービス（Webhook）からPOSTされる	❌	✅
Supabase SDKを使った内部処理	✅	✅（fetch経由の場合）

---

🧪 例①：ユーザー登録（Server Actions）

// src/actions/auth/signUp.ts
"use server";

import { createClient } from "@/utils/supabase/server";

export async function signUpAction(formData: FormData) {
  const email = formData.get("email")?.toString();
  const password = formData.get("password")?.toString();

  const supabase = createClient();
  const { error } = await supabase.auth.signUp({ email, password });

  if (error) {
    throw new Error(error.message);
  }
}

// app/signup/page.tsx
<form action={signUpAction}>
  <input type="email" name="email" />
  <input type="password" name="password" />
  <button type="submit">Sign Up</button>
</form>

✅ フォームから呼び出す処理なので、Server Actions が最適！

🧪 例②：Stripe Webhook（API Routes）

title=app/api/webhooks/stripe/route.ts

import { headers } from "next/headers";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2023-08-16",
});

export async function POST(req: Request) {
  const body = await req.text(); // Stripeはraw bodyが必要
  const sig = headers().get("stripe-signature")!;

  try {
    const event = stripe.webhooks.constructEvent(
      body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    if (event.type === "checkout.session.completed") {
      const session = event.data.object;
      console.log("支払い完了:", session);
      // ここでDB更新などの処理を書く
    }

    return new Response("OK", { status: 200 });
  } catch (err) {
    console.error("Webhook Error:", err);
    return new Response("Webhook Error", { status: 400 });
  }
}

✅ Webhookのように、外部からPOSTされる処理は必ずAPI Routes！

🎯 Server Actions と API Routes の使い分けルールまとめ

1. ユーザーがフォームやボタンを操作する処理 → ✅ Server Actions
2. クライアントJSから fetch で叩きたい処理 → ✅ API Routes
3. 外部サービス（Stripeなど）から呼び出される処理 → ✅ API Routes
4. Supabase を使った内部のDB処理 → ✅ Server Actions でOK（UI連携時)

✅ おわりに

Next.js App Router × Supabase の開発では、
Server Actions と API Routes を正しく使い分けることで、パフォーマンス・保守性・セキュリティを高いレベルで両立できます。

• UIからの操作やフォーム送信 → Server Actions
• 外部サービスからのWebhook、fetchを使った通信 → API Routes

このルールを意識するだけで、コードはスッキリ、開発もスムーズになります。

この記事が、あなたのNext.js + Supabase開発の手助けになれば嬉しいです 🙌