gs-nextjs-server-actions_skill

Overview

This skill explains how to implement thin adapter Next.js Server Actions using ZSA. It focuses on resolving Use Cases from a DI container, delegating all business logic to application layer Use Cases, and returning DTOs. Use it to create consistent, testable API endpoints in the Presentation layer.

How this skill works

Each server action is a minimal adapter: it marks the file as server-only, validates input with Zod, resolves the appropriate Use Case from the DI container, calls the Use Case's execute() with composed input (e.g., adding userId from auth), and returns the resulting DTO. Authentication and common context are provided via predefined authedProcedure and publicProcedure helpers. Mutations can trigger Next.js revalidation hooks (revalidatePath/revalidateTag) in onComplete handlers.

When to use it

• Implementing API endpoints in the Presentation layer that must stay thin and delegative
• Exposing Use Case behavior to client and server callers without leaking domain logic
• Creating consistent action files for CRUD operations (create, update, delete, get, list)
• Adding server-only endpoints that require authenticated context or public access
• Needing automatic propagation of domain errors to the caller

Best practices

• Keep action handlers 3–5 lines: resolve Use Case, call execute(), return DTO
• Always resolve Use Cases from the DI container; avoid direct instantiation
• Restrict Zod to input shape validation; place business rules in Entities/Use Cases
• Include 'use server' and import 'server-only' as the first lines of every action file
• Use onComplete to call revalidatePath/revalidateTag after mutations when needed

Example use cases

• createCategoryAction: validate input, resolve CreateCategoryUseCase, execute with ctx.user.id
• getCategoryAction: accept id, resolve GetCategoryUseCase, return DTO for single entity
• listCategoriesAction: accept limit/cursor, resolve ListCategoriesUseCase, support pagination
• updateCategoryAction: run Use Case then revalidate listing path via onComplete
• Calling actions from client via useServerAction or from server by invoking the action directly