astro-7

Covers initial project setup and migration from Astro 5/6, including breaking changes and Node 22.12+ requirements. Does not cover Content Layer API details (astro-content), Server Actions (astro-actions), Islands hydration directives (astro-islands), UI framework integrations (astro-integrations), or deployment adapters (astro-deployment) — those live in their own skills.

Astro 7 Expert

Production-ready web framework for content-driven sites with unified dev runtime and Islands Architecture.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

fuse-ai-pilot:explore-codebase - Analyze existing routes, layouts, and config
fuse-ai-pilot:research-expert - Verify latest Astro 7 docs via Context7/Exa
mcp__context7__query-docs - Check breaking changes v6→v7

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

When to Use

Building new content-driven websites or blogs
Migrating from Astro 6 to version 7
Configuring static or server output (hybrid = per-route prerender)
Setting up middleware for auth or redirects
Leveraging the new Rust compiler for large sites
Implementing Content Security Policy (CSP) headers

Why Astro 7

Feature	Benefit
Unified Dev Runtime	Dev matches production — fewer "works in dev, breaks in prod" bugs
Vite Environment API (Vite 8)	Exact production runtime during development
Single Rust Compiler	Go compiler removed — one Rust compiler for `.astro` files, with strict HTML parsing (unclosed tags now error instead of being silently auto-corrected)
Live Content Collections	Real-time data from external sources
Built-in Fonts API (stable)	Zero-config font loading with performance optimization
CSP Support (stable)	Built-in Content Security Policy nonce management
Cloudflare Workers	First-class support with workerd runtime in dev
Route caching (stable in 7.0)	Top-level `cache` + `routeRules`, `Astro.cache.set({ maxAge, swr, tags })`
Advanced Routing (7.0)	Optional `src/fetch.ts` entrypoint (`astro/fetch`, `astro/hono`)

Core Concepts

Output Modes

Mode	Description	Use Case
`static` (default)	All pages prerendered at build	Blogs, docs, marketing
`server`	All pages rendered on demand	Apps, dashboards, auth
Hybrid (not an `output` value)	`static` or `server` + per-route `export const prerender`	Most production sites

Routing

File-based routing — src/pages/ maps directly to URLs
Dynamic routes — [slug].astro, [...all].astro
Per-route prerender — export const prerender = false/true
Endpoints — .ts/.js files in src/pages/ for API routes

Reference Guide

Need	Reference
Initial setup	installation.md
Routing patterns	routing.md
Output configuration	output-modes.md
Middleware setup	middleware.md
astro.config.ts	config.md
New Astro 7 features	new-features.md
Full project setup	templates/basic-setup.md
Config examples	templates/config-example.md

Best Practices

Use output: 'static' by default — Add server only when needed
Per-route prerender — Fine-grained hybrid control (output only accepts 'static' | 'server'; there is no 'hybrid' value)
Middleware for cross-cutting concerns — Auth, redirects, headers
No compiler flag needed — the Rust compiler is the only compiler now (Go removed); watch for strict HTML parsing errors on unclosed tags
CSP hashes — Use built-in stable security.csp (hash-based, plus the Astro.csp runtime API) instead of custom headers
Node 22.12+ required — odd-numbered Node versions are unsupported; stay on stable TypeScript tooling, the native tsgo compiler can make astro check/typecheck fail opaquely (see installation.md)