astro-actions git:20260904.5f1d30fA

Immutable. This exact content is served forever at /api/v1/blob/a24448c233e26189.

---
name: astro-actions
description: Use when handling form submissions, mutations, or server-side logic with type safety in Astro via defineAction / astro:actions.
versions:
  astro: 7
  zod: 4
user-invocable: true
references: 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.md
related-skills: astro-7, astro-content, astro-islands
---

<objective>
Implements 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.

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.
</objective>

# 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`:

1. **fuse-ai-pilot:explore-codebase** - Check existing actions in `src/actions/`
2. **fuse-ai-pilot:research-expert** - Verify latest Actions docs via Context7/Exa
3. **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:

```typescript
// 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](references/overview.md) |
| defineAction patterns | [defining-actions.md](references/defining-actions.md) |
| ActionError handling | [error-handling.md](references/error-handling.md) |
| HTML form integration | [forms.md](references/forms.md) |
| Progressive enhancement | [progressive-enhancement.md](references/progressive-enhancement.md) |
| Contact form template | [templates/contact-form.md](references/templates/contact-form.md) |
| JSON action template | [templates/json-action.md](references/templates/json-action.md) |

---

## Best Practices

1. **Always define `input` schema** — Never skip Zod validation
2. **Use `ActionError` for known errors** — Standardized codes for client handling
3. **`accept: 'form'` for HTML forms** — Native form submission support
4. **Progressive enhancement** — Form works without JS, enhanced with it
5. **Check `ctx.cookies` for auth** — Throw `UNAUTHORIZED` when not logged in