server-actions
在使用next-safe-action创建或修改服务器操作时执行Head Shakers服务器操作编码约定,并确保使用项目的useServerAction钩子进行一致的客户端消费模式。此技能涵盖服务器端操作实现和前端集成模式。
📖 中文导读:在使用next-safe-action创建或修改服务器操作时执行Head Shakers服务器操作编码约定,并确保使用项目的useServerAction钩子进行一致的客户端消费模式。此技能涵盖服务器端操作实现和前端集成模式。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: server-actions description: Enforces project server actions coding conventions when creating or modifying server actions using next-safe-action, and ensures consistent client-side consumption patterns using the project's useServerAction hook. This skill covers both server-side action implementation and frontend integration patterns.
Server Actions Skill
Purpose
This skill enforces the project server actions coding conventions automatically during server action development. It ensures consistent patterns for authentication, validation, error handling, Sentry integration, cache invalidation, and client-side consumption via the useServerAction hook.
Activation
This skill activates when:
- Creating new server actions in
src/lib/actions/ - Modifying existing server action files (
.actions.ts) - Implementing form submissions that call server actions
- Working with the next-safe-action library
- Creating components that consume server actions via
useServerAction - Implementing dialogs, forms, or features that require mutations
Workflow
- Detect server action work (file path contains
actions/or imports fromnext-safe-actionoruse-server-action) - Load
references/Server-Actions-Conventions.md - Generate/modify code following all conventions
- Scan for violations of server action patterns (both server-side and client-side)
- Auto-fix all violations (no permission needed)
- Report fixes applied
Server-Side Key Patterns
- Use
authActionClient,adminActionClient, orpublicActionClientbased on auth requirements - Always use
ctx.sanitizedInputparsed through Zod schema (never useparsedInputdirectly) - Include proper metadata with
actionNameandisTransactionRequired - Use
withActionErrorHandling()wrapper for automatic Sentry context, breadcrumbs, and error handling (recommended) - Alternatively, use
withActionBreadcrumbs()for breadcrumbs without error handling - Use
trackCacheInvalidation()to log cache failures as warnings without throwing - Use facades for business logic (actions should be thin orchestrators)
- Handle errors with
handleActionErrorutility (automatic withwithActionErrorHandling) - Invalidate cache after mutations using
CacheRevalidationService - Return consistent response shape:
{ success, message, data }
Client-Side Key Patterns
- Always use
useServerActionhook from@/hooks/use-server-action(neveruseActiondirectly) - Use
executeAsyncwithtoastMessagesfor user-initiated mutations - Use
executewithisDisableToast: truefor silent background operations - Use
breadcrumbContextfor Sentry tracking on user-initiated actions (providesactionandcomponentnames) - Access results via
data.datain callbacks orresult?.data?.datafrom result object - Use
isExecutingfor loading states and button disabled states - Integrate with
useAppFormfor form submissions with focus management - Use
withFocusManagementHOC anduseFocusContextfor form error focusing
Usage Pattern Reference
| Use Case | Hook Setup | Execution |
|---|---|---|
| Form submission | toastMessages + onSuccess |
await executeAsync(value) |
| Delete with navigation | toastMessages |
await executeAsync(id).then(redirect) |
| Search/autocomplete | isDisableToast: true |
execute(query) in useEffect |
| Silent background ops | isDisableToast: true |
execute(data) in callback |
| Availability check | isDisableToast: true |
execute(value) in useEffect |
References
references/Server-Actions-Conventions.md- Complete server actions conventions (server & client)