| name | nextjs-server-actions |
| description | Mutations, Form handling, and RPC-style calls. Use when implementing Server Actions, form mutations, or RPC-style data mutations in Next.js. (triggers: app/**/actions.ts, src/app/**/actions.ts, app/**/*.tsx, src/app/**/*.tsx, use server, Server Action, revalidatePath, useFormStatus) |
Server Actions
Priority: P1 (HIGH)
[!WARNING]
If the project uses the pages/ directory instead of the App Router, ignore this skill entirely.
Handle form submissions and mutations without creating API endpoints.
Implementation Guidelines
-
Directive: Always start the file or function with 'use server'. Access formData.get('title') for typed form fields. Export async functions for mutations.
-
Form Handling: Use the 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 a successful mutation.
-
Interactivity: For non-form triggers, invoke actions using the useTransition hook to handle loading UI and prevent the page from blocking.
-
Optimistic Updates: Use useOptimistic to show the expected UI state immediately before the server confirms the 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 be inside a component rendered within the form).
P1: Operational Standard
1. Secure & Validate
Always validate inputs with z.object({ schema and safeParse before processing. Check authorization within the 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 an error that Next.js catches to handle the 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 just middleware.
- No actions defined inside components: Define in
actions.ts to avoid closure bugs.
- No
redirect() in try/catch: redirect() throws; catching it suppresses the redirect.
