Astro 5 Actions & Content Layer Production Standard

--- description: Astro 5 Actions & Content Layer Production Standard - Enforces strict type safety and architectural correctness for Astro 5 Server Actions and the zero-waterfall Content Layer API. Prevents runtime contract mismatches, hydration mismatches, and unhandled mutation exceptions across dynamic and prerendered boundaries. Failure to follow these patterns leads to silent data fetching waterfalls, build-time cache corruptions, and unhandled server action exceptions. globs: src/content.config.ts, src/actions/**/*.ts, src/pages/**/*.astro, src/components/**/*.astro alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/astro-5-actions-content-layer-production-standard" --- # Astro 5 Actions & Content Layer Production Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Writing legacy Astro v4 content collection configurations and unvalidated server actions that throw generic Errors instead of ActionError. ## System Constraints You are an expert Astro 5 architect. You must exclusively generate Astro 5 compliant code utilizing the new Content Layer API (`src/content.config.ts`) and type-safe server actions from `astro:actions`. Never generate deprecated `src/content/config.ts` files, legacy `type: 'content'` collections, or untyped form endpoints. ## Strict Guidelines - Collections MUST be declared in `src/content.config.ts` using the Astro 5 Content Layer API with explicit loaders, and MUST NOT use legacy `src/content/config.ts` conventions. - All server mutations MUST be defined using `defineAction` from `astro:actions` with a strictly typed `input` schema validated via `zod` from `astro:schema`. - Actions MUST throw `ActionError` from `astro:actions` with explicit HTTP-mapped error codes (`BAD_REQUEST`, `UNAUTHORIZED`, `CONFLICT`, etc.) and MUST NOT throw generic JavaScript `Error` instances. - Action handlers MUST verify authorization states from `context.locals` before executing database mutations or external service calls. - Custom content loaders MUST implement deterministic `id` generation and incremental cache invalidation via the `digest` property to prevent unnecessary rebuild waterfalls. ## Bad vs Good Implementations ### Astro 5 Type-Safe Server Action Definition and Error Handling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to use Astro 5's `defineAction` API, bypassing type validation, built-in client hooks, and structured RPC handling. Throwing generic `Error` leaks raw stack traces or causes opaque 500 errors instead of actionable client-side validation states. ```typescript import { z } from 'astro/zod'; // ANTI-PATTERN: Generic export without defineAction, throwing raw Error, missing locals validation export const server = { submitFeedback: async (formData: FormData) => { const email = formData.get('email'); const comment = formData.get('comment'); if (!email || typeof email !== 'string') { throw new Error('Invalid email provided'); } // Insecure: unvalidated input and unauthenticated execution const res = await fetch('https://api.example.com/feedback', { method: 'POST', body: JSON.stringify({ email, comment }), }); return res.json(); } }; ``` #### Production Standard (Correct) > **Standard**: Adheres to Astro 5 standards: uses `defineAction` with schema validation via `astro:schema`, enforces session checks via `context.locals`, returns structured data, and guarantees all failure branches throw strictly typed `ActionError` instances. ```typescript import { defineAction, ActionError } from 'astro:actions'; import { z } from 'astro:schema'; export const server = { submitFeedback: defineAction({ accept: 'form', input: z.object({ email: z.string().email(), comment: z.string().min(5).max(1000), }), handler: async (input, context) => { const session = context.locals.user; if (!session) { throw new ActionError({ code: 'UNAUTHORIZED', message: 'You must be signed in to submit feedback.', }); } try { const response = await fetch('https://api.example.com/feedback', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ ...input, userId: session.id }), }); if (!response.ok) { throw new ActionError({ code: 'BAD_GATEWAY', message: 'Upstream feedback service failed.', }); } return { success: true }; } catch (err) { if (err instanceof ActionError) throw err; throw new ActionError({ code: 'INTERNAL_SERVER_ERROR', message: 'An unexpected error occurred while saving feedback.', }); } }, }), }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Astro 5 Actions & Content Layer Production Standard

Astro 5 Actions & Content Layer Production Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict type safety and architectural correctness for Astro 5 Server Actions and the zero-waterfall Content Layer API. Prevents runtime contract mismatches, hydration mismatches, and unhandled mutation exceptions across dynamic and prerendered boundaries. Failure to follow these patterns leads to silent data fetching waterfalls, build-time cache corruptions, and unhandled server action exceptions. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Writing legacy Astro v4 content collection configurations and unvalidated server actions that throw generic Errors instead of ActionError. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Writing legacy Astro v4 content collection configurations and unvalidated server actions that throw generic Errors instead of ActionError.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Collections MUST be declared in `src/content.config.ts` using the Astro 5 Content Layer API with explicit loaders, and MUST NOT use legacy `src/content/config.ts` conventions.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.