- **Server Actions** are async functions marked with `"use server"` that run on the server and get called directly from your React components. Use them for internal mutations: form submissions, button triggered state changes, anything your own UI initiates. - **Route Handlers** are traditional HTTP endpoints living in `app/api/`. Use them when something external needs to call your backend: webhooks, mobile apps, third party integrations, cacheable GET endpoints. - **The one question that decides it:** Is the caller your own React code or something outside your app? Internal means Server Action. External means Route Handler.

## The Core Difference Both Server Actions and Route Handlers run on the server. Both can read your database, call external APIs, and handle sensitive logic. The difference is not about what they do. It's about who calls them and how. A Server Action is a function. You call it like a function. Next.js handles the HTTP request behind the scenes. The caller is always your React code. A Route Handler is an HTTP endpoint. It lives at a URL. Anything that can make an HTTP request can reach it, whether that's your React code, a Stripe webhook, a mobile app, or a CLI script. That single distinction drives every decision in this guide. | | Server Actions | Route Handlers | |---|---|---| | Called from | React components only | Any HTTP client | | HTTP method | POST only | GET, POST, PUT, DELETE, PATCH | | Type safety | Automatic | Manual | | Caching | Not cacheable | GET requests cacheable | | Progressive enhancement | Yes | No | | External access | No | Yes | | Best for | Internal mutations | External APIs, webhooks | Tested against Next.js 16 and React 19.

## What Are Server Actions Server Actions are async functions with a `"use server"` directive. They run on the server and get called directly from Server or Client Components without any fetch logic on your end. ```ts // app/actions/posts.ts "use server"; import { revalidatePath } from "next/cache"; import { db } from "@/lib/db"; export async function createPost(formData: FormData) { const title = formData.get("title") as string; await db.posts.create({ data: { title } }); revalidatePath("/posts"); } ``` Call it from a form in a Server Component: ```tsx // app/posts/new/page.tsx import { createPost } from "@/app/actions/posts"; export default function NewPostPage() { return ( ); } ``` No fetch call. No API route file. No request or response objects. The function runs on the server and Next.js handles everything in between. One thing worth knowing about Next.js 16: if your Server Action needs to read cookies or headers, those calls must now be awaited. ```ts "use server"; import { cookies } from "next/headers"; export async function getSessionData() { const cookieStore = await cookies(); const token = cookieStore.get("session")?.value; } ``` This is a breaking change from Next.js 15 where `cookies()` was synchronous. If you're migrating an existing codebase, run the Next.js codemod and it handles this automatically: ```bash npx @next/codemod@canary upgrade latest ```

## What Are Route Handlers Route Handlers are traditional HTTP endpoints. You create a `route.ts` file under `app/api/` and export functions named after HTTP methods. ```ts // app/api/posts/route.ts import { NextRequest, NextResponse } from "next/server"; import { db } from "@/lib/db"; export async function GET() { const posts = await db.posts.findMany(); return NextResponse.json(posts); } export async function POST(request: NextRequest) { const { title } = await request.json(); const post = await db.posts.create({ data: { title } }); return NextResponse.json(post, { status: 201 }); } ``` Route Handlers give you full control over HTTP: status codes, headers, streaming responses, CORS configuration, and caching directives. Any client that can make an HTTP request can call them. In Next.js 16, `params` in dynamic Route Handlers must be awaited: ```ts // app/api/posts/[id]/route.ts import { NextRequest, NextResponse } from "next/server"; export async function GET( request: NextRequest, { params }: { params: Promise<{ id: string }> } ) { const { id } = await params; const post = await db.posts.findUnique({ where: { id } }); if (!post) { return NextResponse.json({ error: "Not found" }, { status: 404 }); } return NextResponse.json(post); } ``` Same async params change as Server Actions and page components in Next.js 16. If you see a runtime error about params not being awaited, that's what's happening.

## When to Use Server Actions Use Server Actions when the caller is your own React code and the operation changes data. Good fits for Server Actions: - Form submissions (signup, login, contact forms, profile updates) - Button triggered mutations (delete a record, toggle a setting, publish a post) - Any create, update, or delete operation that your UI initiates - Operations that need to revalidate cached data after running Real patterns from a SaaS product: ```ts // app/actions/auth.ts "use server"; import { redirect } from "next/navigation"; import { createSession } from "@/lib/auth"; export async function login(formData: FormData) { const email = formData.get("email") as string; const password = formData.get("password") as string; const user = await validateCredentials(email, password); if (!user) { return { error: "Invalid credentials" }; } await createSession(user.id); redirect("/dashboard"); } ``` ```ts // app/actions/billing.ts "use server"; import { revalidatePath } from "next/cache"; export async function cancelSubscription(subscriptionId: string) { await stripe.subscriptions.cancel(subscriptionId); await db.subscriptions.update({ where: { stripeId: subscriptionId }, data: { status: "canceled" }, }); revalidatePath("/billing"); } ``` Do not use Server Actions for: - GET requests: Server Actions are POST only and can't be cached. - Webhook endpoints: external services can't call Server Actions. - Public APIs: third party clients can't reach Server Actions directly. - Fetching data: do that directly in Server Components instead.

## When to Use Route Handlers Use Route Handlers when the caller is outside your Next.js app, when you need a cacheable GET endpoint, or when you need full control over the HTTP response. Good fits for Route Handlers: - Webhook endpoints from Stripe, Clerk, Resend, GitHub - Public REST APIs for mobile apps or third parties - Cacheable GET endpoints for data that doesn't change often - OAuth callbacks - Health check endpoints - Streaming responses Real patterns from a SaaS product: ```ts // app/api/webhooks/stripe/route.ts import { NextRequest, NextResponse } from "next/server"; import Stripe from "stripe"; export async function POST(request: NextRequest) { const body = await request.text(); const signature = request.headers.get("stripe-signature") as string; let event: Stripe.Event; try { event = stripe.webhooks.constructEvent( body, signature, process.env.STRIPE_WEBHOOK_SECRET! ); } catch { return NextResponse.json( { error: "Invalid signature" }, { status: 400 } ); } switch (event.type) { case "customer.subscription.deleted": await handleSubscriptionDeleted(event.data.object); break; case "invoice.payment_succeeded": await handlePaymentSucceeded(event.data.object); break; } return NextResponse.json({ received: true }); } ``` ```ts // app/api/v1/projects/route.ts import { NextRequest, NextResponse } from "next/server"; export async function GET(request: NextRequest) { const authHeader = request.headers.get("authorization"); if (!authHeader?.startsWith("Bearer ")) { return NextResponse.json({ error: "Unauthorized" }, { status: 401 }); } const projects = await db.projects.findMany(); return NextResponse.json(projects, { headers: { "Cache-Control": "public, max-age=60, stale-while-revalidate=300", }, }); } ``` Do not use Route Handlers for: - Internal form submissions from your own UI. A Server Action is simpler and gives you type safety automatically. - Mutations only your React code triggers. You lose progressive enhancement and write more boilerplate for no real benefit.

## Validation with Zod Both need input validation. Never trust what comes in from the client. Zod is the standard in the Next.js ecosystem and works well with both patterns. Server Action with Zod: ```ts // app/actions/posts.ts "use server"; import { z } from "zod"; import { revalidatePath } from "next/cache"; const createPostSchema = z.object({ title: z.string().min(1).max(200), content: z.string().min(1), }); export async function createPost(formData: FormData) { const raw = { title: formData.get("title"), content: formData.get("content"), }; const result = createPostSchema.safeParse(raw); if (!result.success) { return { error: result.error.flatten().fieldErrors, }; } await db.posts.create({ data: result.data }); revalidatePath("/posts"); return { success: true }; } ``` Route Handler with Zod: ```ts // app/api/posts/route.ts import { NextRequest, NextResponse } from "next/server"; import { z } from "zod"; const createPostSchema = z.object({ title: z.string().min(1).max(200), content: z.string().min(1), }); export async function POST(request: NextRequest) { const body = await request.json(); const result = createPostSchema.safeParse(body); if (!result.success) { return NextResponse.json( { error: result.error.flatten().fieldErrors }, { status: 400 } ); } const post = await db.posts.create({ data: result.data }); return NextResponse.json(post, { status: 201 }); } ``` The validation logic is the same. The difference is what you do with the error. Server Actions return an object your component handles. Route Handlers return an HTTP response with a status code. Same input, different output surface.

## Security Server Actions look like regular functions. That's exactly what makes them feel safer than they are. They're still public HTTP endpoints. The `"use server"` directive tells Next.js to run the function on the server. It doesn't add any authentication. If someone crafts a POST request to the right URL with the right payload, they can trigger your Server Action. Always authenticate and authorize inside every protected action. ```ts // app/actions/posts.ts "use server"; import { getSession } from "@/lib/auth"; export async function deletePost(postId: string) { const session = await getSession(); if (!session?.user) { throw new Error("Not authenticated"); } const post = await db.posts.findUnique({ where: { id: postId } }); if (!post) { throw new Error("Not found"); } if (post.authorId !== session.user.id) { throw new Error("Not authorized"); } await db.posts.delete({ where: { id: postId } }); } ``` A few rules worth keeping front of mind: Never expose database IDs from the client without checking ownership server side. Don't assume a session is valid just because it exists, verify it on every protected action. Rate limit sensitive operations like login and signup. And log auth failures. A flood of them is usually the first sign something is wrong. For webhook Route Handlers, always verify the webhook signature before processing. Stripe, Clerk, Resend, and most providers include a signature header and a verification method. Skip this step and anyone can hit your webhook endpoint with fake payloads.

## Error Handling Server Actions and Route Handlers handle errors differently because they communicate differently. Server Actions return values. They don't throw to the client: ```ts // app/actions/posts.ts "use server"; export async function createPost(formData: FormData) { try { const title = formData.get("title") as string; if (!title) { return { success: false, error: "Title is required" }; } await db.posts.create({ data: { title } }); revalidatePath("/posts"); return { success: true }; } catch (err) { console.error("[createPost] error:", err); return { success: false, error: "Something went wrong" }; } } ``` Handle the result in your component with `useActionState`: ```tsx // app/posts/new/page.tsx "use client"; import { createPost } from "@/app/actions/posts"; import { useActionState } from "react"; export default function NewPostPage() { const [state, action, isPending] = useActionState(createPost, null); return ( ); } ``` `useActionState` is the React 19 hook for handling Server Action state in Client Components. It replaced the older `useFormState`. You get the last returned value from the action and a pending boolean for loading UI. Route Handlers return HTTP responses with explicit status codes: ```ts // app/api/posts/route.ts export async function POST(request: NextRequest) { try { const body = await request.json(); const result = createPostSchema.safeParse(body); if (!result.success) { return NextResponse.json( { error: result.error.flatten().fieldErrors }, { status: 400 } ); } const post = await db.posts.create({ data: result.data }); return NextResponse.json(post, { status: 201 }); } catch (err) { console.error("[POST /api/posts] error:", err); return NextResponse.json( { error: "Internal server error" }, { status: 500 } ); } } ``` Use the right status codes. 400 for bad input. 401 for unauthenticated. 403 for unauthorized. 404 for not found. 429 for rate limited. 500 for unexpected errors. External clients depend on these to handle failures correctly.

## Folder Structure Keep Server Actions and Route Handlers in separate, predictable locations. Mixing them creates confusion fast. ``` src/ app/ api/ webhooks/ stripe/ route.ts clerk/ route.ts v1/ projects/ route.ts [id]/ route.ts actions/ auth.ts billing.ts posts.ts profile.ts dashboard/ page.tsx posts/ page.tsx new/ page.tsx ``` Server Actions go in `app/actions/` grouped by domain. Route Handlers go under `app/api/` organized by resource. Webhooks get their own subfolder. Version your public API from the start with `app/api/v1/` because adding versioning later is painful.

## The Decision Framework Ask these questions in order. **Is the caller outside your Next.js app?** Yes — use a Route Handler. External clients can't call Server Actions. **Is it a read operation?** Yes, needs HTTP caching — use a Route Handler with a GET endpoint. Yes, no caching needed — fetch directly in a Server Component. **Is it a mutation triggered from your own UI?** Yes — use a Server Action. Most SaaS products end up with Server Actions handling around 90 percent of server code and Route Handlers covering webhook endpoints and whatever public API surface exists. That's the right default.

## Common Mistakes **Using Server Actions for data fetching.** Server Actions are POST only and can't be cached. Fetch data directly in a Server Component or use a Route Handler with a GET endpoint. **Creating Route Handlers for internal mutations.** If only your React components call the endpoint, a Server Action is simpler and gives you type safety for free. The extra request and response handling is overhead you don't need. **Forgetting that Server Actions are public endpoints.** The `"use server"` directive doesn't add authentication. Every Server Action that touches user data needs an auth check. **Not awaiting `cookies()` and `headers()` in Next.js 16.** These are async now. Not awaiting them causes a runtime error that's hard to trace if you're not expecting it. **Mixing Server Action files into `app/api/`.** Server Actions in `app/actions/`, Route Handlers in `app/api/`. Keep them separate.

## Wrap Up Server Actions and Route Handlers solve different problems. Server Actions are the default for anything your own UI initiates. Route Handlers are the default for anything that needs a URL an external client can call. When you're not sure, start with a Server Action. You can always extract a Route Handler later if you need external access. Going the other direction is more work. If you're building a SaaS and want your project management, deployment tracking, and analytics in one place, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What is the difference between Server Actions and API Routes in Next.js? Server Actions are async functions you call directly from React components. They run on the server but are invoked like regular functions, with no fetch call needed. API Routes (Route Handlers in the App Router) are traditional HTTP endpoints that live at a URL and can be called by any HTTP client. Use Server Actions for internal mutations from your own UI. Use Route Handlers when something external needs to call your backend. ## Can Server Actions replace API Routes in Next.js? Not entirely. Server Actions are great for internal mutations triggered by your own React code. But they can't replace Route Handlers for webhooks, public REST APIs, OAuth callbacks, streaming responses, or any use case where an external client needs to call a stable URL. Most real apps use both. ## Are Server Actions secure in Next.js? Server Actions run on the server but they are still public HTTP endpoints. The `"use server"` directive does not add authentication. Anyone who can craft the right POST request can trigger a Server Action. Every Server Action that touches user data needs explicit authentication and authorization checks inside the function. ## Can you use Server Actions for GET requests? No. Server Actions only support POST requests and cannot be cached. For data fetching, fetch directly in a Server Component or use a Route Handler with a GET endpoint and HTTP caching headers. ## When should I use a Route Handler instead of a Server Action? Use a Route Handler when the caller is outside your Next.js app. Webhooks from Stripe, Clerk, or Resend need a public URL. Mobile apps and third party integrations need a stable HTTP endpoint. OAuth callbacks are GET requests from external services. Any of these require a Route Handler. Server Actions are for mutations your own UI triggers. ## What is `useActionState` in Next.js? `useActionState` is a React 19 hook for handling Server Action responses in Client Components. It replaced the older `useFormState` hook. It gives you the last returned value from a Server Action and a pending boolean you can use for loading UI. Wire it to a form action and you get optimistic UI and error handling without any manual fetch logic. ## Do Server Actions work without JavaScript? Yes. When a Server Action is used as a form action in a Server Component, the form works even if JavaScript hasn't loaded yet. This is called progressive enhancement. Route Handlers do not have this behavior since they require a client-side fetch call.