nextjs-server-actions-and-route-handlers

Next.js Server Actions and Route Handlers

Use this skill when the task is primarily about mutation boundaries, server-only execution, or deciding whether code belongs in a Server Action or a Route Handler.

Scope

• use server and Server Function placement
• Server Actions for form and UI-driven mutations
• Route Handlers for explicit HTTP endpoints
• redirects, refreshes, cookies, and post-mutation cache invalidation
• request and response handling with NextRequest and NextResponse
• auth and validation guardrails for mutation surfaces

Routing cues

• use server, form actions, mutation flow, cookies, redirects, or Route Handlers -> use this skill
• cache strategy and invalidation ownership as the main question -> use nextjs-data-fetching-and-cache
• metadata, sitemap, or robots concerns -> use nextjs-metadata-seo-and-file-conventions
• runtime placement or proxy.ts as the main concern -> use nextjs-rendering-runtime-and-middleware

Default path

1. Read references/server-boundaries-and-handler-selection.md first.
2. Decide whether the caller is UI-bound or protocol-bound before writing code.
3. Validate input and enforce auth inside every Server Action and Route Handler.
4. Pair mutations with explicit cache refresh strategy instead of relying on incidental reloads.

When to deviate

• Prefer a Route Handler when the caller is external, protocol-specific, or not driven by your own UI.
• Prefer a Server Action when the mutation is initiated directly from your app UI or a form.
• Move to the cache skill when the hard problem is invalidation strategy rather than mutation boundary choice.
• Move to the runtime skill when the real question is execution placement or interception before the route runs.

Quick example

'use server'

import { revalidatePath } from 'next/cache'

export async function savePost(formData: FormData) {
  await db.post.create({
    data: { title: String(formData.get('title') ?? '') },
  })
  revalidatePath('/posts')
}