Covers the full action lifecycle from src/actions/index.ts structure through error handling and redirect patterns. Does not cover Astro DB integration in depth (astro-db handles the database layer) or Content Layer schemas (astro-content) — this skill focuses on the request/validation/response boundary.
Astro Actions Expert
Type-safe server functions with automatic validation, standardized errors, and progressive enhancement.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Check existing actions in
src/actions/
- fuse-ai-pilot:research-expert - Verify latest Actions docs via Context7/Exa
- mcp__context7__query-docs - Get defineAction and ActionError examples
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Handling form submissions with server-side validation
- Creating type-safe backend mutations without API boilerplate
- Building progressive enhancement (works without JS)
- Replacing API endpoints for client-server communication
Why Astro Actions
| Feature |
Benefit |
defineAction() |
Type-safe server function definition |
| Zod validation |
Automatic JSON and FormData parsing |
ActionError |
Standardized error codes and messages |
accept: 'form' |
Direct HTML form submission support |
| Progressive enhancement |
Works without JavaScript enabled |
astro:actions |
Client import for type-safe calls |
Core Concepts
Action Structure
All actions live in src/actions/index.ts and export a server object:
// src/actions/index.ts
import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';
export const server = {
myAction: defineAction({ /* ... */ })
}
Accept Modes
| Mode |
Description |
accept: 'json' (default) |
Parses JSON request body |
accept: 'form' |
Parses HTML FormData directly |
Error Codes
Standard HTTP-aligned codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST, INTERNAL_SERVER_ERROR, CONFLICT, TOO_MANY_REQUESTS.
Reference Guide
| Need |
Reference |
| Concepts & architecture |
overview.md |
| defineAction patterns |
defining-actions.md |
| ActionError handling |
error-handling.md |
| HTML form integration |
forms.md |
| Progressive enhancement |
progressive-enhancement.md |
| Contact form template |
templates/contact-form.md |
| JSON action template |
templates/json-action.md |
Best Practices
- Always define
input schema — Never skip Zod validation
- Use
ActionError for known errors — Standardized codes for client handling
accept: 'form' for HTML forms — Native form submission support
- Progressive enhancement — Form works without JS, enhanced with it
- Check
ctx.cookies for auth — Throw UNAUTHORIZED when not logged in
1---2name: astro-actions3description: Use when handling form submissions, mutations, or server-side logic with type safety in Astro via defineAction / astro:actions.4versions:5 astro: 76 zod: 47user-invocable: true8references: references/overview.md, references/defining-actions.md, references/error-handling.md, references/forms.md, references/progressive-enhancement.md, references/templates/contact-form.md, references/templates/json-action.md9related-skills: astro-7, astro-content, astro-islands10metadata:11 source: https://skillmd.com/skills/fusengine/astro-actions12---1314<objective>15Implements Astro Server Actions: `defineAction()` with Zod-validated `input`, the `astro:actions` client import for type-safe calls, standardized `ActionError` codes (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST, INTERNAL_SERVER_ERROR, CONFLICT, TOO_MANY_REQUESTS), `accept: 'form'` for direct HTML form submission, and progressive enhancement so forms work without JavaScript.1617Covers the full action lifecycle from `src/actions/index.ts` structure through error handling and redirect patterns. Does not cover Astro DB integration in depth (astro-db handles the database layer) or Content Layer schemas (astro-content) — this skill focuses on the request/validation/response boundary.18</objective>1920# Astro Actions Expert2122Type-safe server functions with automatic validation, standardized errors, and progressive enhancement.2324## Agent Workflow (MANDATORY)2526Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:27281. **fuse-ai-pilot:explore-codebase** - Check existing actions in `src/actions/`292. **fuse-ai-pilot:research-expert** - Verify latest Actions docs via Context7/Exa303. **mcp__context7__query-docs** - Get defineAction and ActionError examples3132After implementation, run **fuse-ai-pilot:sniper** for validation.3334---3536## Overview3738### When to Use3940- Handling form submissions with server-side validation41- Creating type-safe backend mutations without API boilerplate42- Building progressive enhancement (works without JS)43- Replacing API endpoints for client-server communication4445### Why Astro Actions4647| Feature | Benefit |48|---------|---------|49| `defineAction()` | Type-safe server function definition |50| Zod validation | Automatic JSON and FormData parsing |51| `ActionError` | Standardized error codes and messages |52| `accept: 'form'` | Direct HTML form submission support |53| Progressive enhancement | Works without JavaScript enabled |54| `astro:actions` | Client import for type-safe calls |5556---5758## Core Concepts5960### Action Structure6162All actions live in `src/actions/index.ts` and export a `server` object:6364```typescript65// src/actions/index.ts66import { defineAction } from 'astro:actions';67import { z } from 'astro/zod';6869export const server = {70 myAction: defineAction({ /* ... */ })71}72```7374### Accept Modes7576| Mode | Description |77|------|-------------|78| `accept: 'json'` (default) | Parses JSON request body |79| `accept: 'form'` | Parses HTML FormData directly |8081### Error Codes8283Standard HTTP-aligned codes: `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `BAD_REQUEST`, `INTERNAL_SERVER_ERROR`, `CONFLICT`, `TOO_MANY_REQUESTS`.8485---8687## Reference Guide8889| Need | Reference |90|------|-----------|91| Concepts & architecture | [overview.md](references/overview.md) |92| defineAction patterns | [defining-actions.md](references/defining-actions.md) |93| ActionError handling | [error-handling.md](references/error-handling.md) |94| HTML form integration | [forms.md](references/forms.md) |95| Progressive enhancement | [progressive-enhancement.md](references/progressive-enhancement.md) |96| Contact form template | [templates/contact-form.md](references/templates/contact-form.md) |97| JSON action template | [templates/json-action.md](references/templates/json-action.md) |9899---100101## Best Practices1021031. **Always define `input` schema** — Never skip Zod validation1042. **Use `ActionError` for known errors** — Standardized codes for client handling1053. **`accept: 'form'` for HTML forms** — Native form submission support1064. **Progressive enhancement** — Form works without JS, enhanced with it1075. **Check `ctx.cookies` for auth** — Throw `UNAUTHORIZED` when not logged in