nextjs-server-actions

name	nextjs-server-actions
description	Implement mutations, forms, and RPC-style calls with Next.js Server Actions. Use when implementing Server Actions, form mutations, or RPC-style data mutations in Next.js.
metadata	{"triggers":{"files":["app/**/actions.ts","src/app/**/actions.ts","app/**/*.tsx","src/app/**/*.tsx"],"keywords":["use server","Server Action","revalidatePath","useFormStatus"]}}

Server Actions

Priority: P1 (HIGH)

[!WARNING] If project uses pages/ directory instead of App Router, ignore this skill entirely.

Handle form submissions and mutations without creating API endpoints.

Implementation Guidelines

• Directive: Always start file or function with 'use server'. Access formData.get('title') for typed form fields. Export async functions for mutations.

• Form Handling: Use action prop of <form> to trigger actions via action={createPost}. Use useFormStatus() for pending states — disabled={pending} on buttons. Use useActionState (React 19/Next.js 15) for action={action} form state with <form action={action}>.

• Data Refresh: Trigger UI updates using revalidatePath('/') or revalidateTag('tag-name') after successful mutation.

• Interactivity: For non-form triggers, invoke actions using useTransition hook to handle loading UI and prevent page from blocking.

• Optimistic Updates: Use useOptimistic to show expected UI state immediately before server confirms mutation.

• Security: Sanitize all inputs from FormData. Perform auth checks inside every action (await auth()). Limit file uploads by size and MIME type.

• Form: <form action={createPost}> (Progressive enhancements work without JS).

• Event Handler: onClick={() => createPost(data)}.

• Pending State: Use useFormStatus hook (must inside component rendered within form).

P1: Operational Standard

1. Secure & Validate

Always validate inputs with z.object({ schema and safeParse before processing. Check authorization within action. See Secure Action Example.

2. Pending States

Use useActionState (React 19/Next.js 15+) for state handling and useFormStatus for button loading states.

Constraints

• Closures: Avoid defining actions inside components to prevent hidden closure encryption overhead and serialization bugs.
• Redirection: Use redirect() for success navigation; it throws error that Next.js catches to handle redirect.

Anti-Patterns

• No unvalidated Server Action inputs: Always validate with Zod before processing.
• No skipped auth checks: Verify session/user inside every action, not middleware.
• No actions defined inside components: Define in actions.ts to avoid closure bugs.
• No redirect() in try/catch: redirect() throws; catching it suppresses redirect.