nextjs-server-actions_skill

Overview

This skill teaches implementing Next.js server actions using ZSA (Zod Server Actions) with built-in authentication, validation, and React Query integration. It provides a consistent file pattern, required directives, and examples for protected and public actions. The guidance focuses on thin action handlers that call service layers, handle errors, and trigger Next.js revalidation when needed.

How this skill works

Actions are server-only files that start with 'use server' and import 'server-only' to prevent client imports. Use authedProcedure for authenticated endpoints or createServerAction for public ones, chain .input(.), .output(.), .onComplete(.), and .handler(.). Client code uses useServerActionMutation and useServerActionQuery to integrate with React Query patterns and form libraries like react-hook-form.

When to use it

• Creating API endpoints or form handlers that run on the server
• Implementing create, update, delete, and list mutations with server-side validation
• Protecting actions that require authenticated user context
• Triggering Next.js cache revalidation after mutations
• Integrating server actions with React Query for optimistic UI and caching

Best practices

• Place actions under features/<feature>/usecases/... following the create/update/delete/list action pattern
• Always start action files with 'use server' and import 'server-only' as the second line
• Validate all inputs with Zod schemas and declare outputs where appropriate
• Use authedProcedure for protected actions so ctx.userId is available
• Call the service layer from handlers; keep business logic out of actions
• Use revalidatePath or revalidateTag after successful mutations and avoid exposing internal errors

Example use cases

• Create a create-<entity>-action.ts that validates formData, calls AccountService.create, revalidates '/accounts' and returns the created entity
• Implement update-<entity>-action.ts using authedProcedure to ensure only the owner can update
• Build list-<entity>-action.ts as a read query used via useServerActionQuery on the client for server-rendered lists
• Wire a React Hook Form create form to useServerActionMutation for submission with zodResolver validation
• Use onComplete to revalidate pages or tags after delete or update mutations