/astro-7

name: astro-7
description: Use when building Astro 7 sites, choosing an output mode (static/server, hybrid via per-route prerender), configuring middleware, or upgrading from Astro 5/6.
versions:
  astro: "7"
  node: "22.23.4+"
  vite: 8
user-invocable: true
references: references/installation.md, references/routing.md, references/output-modes.md, references/middleware.md, references/config.md, references/new-features.md, references/templates/basic-setup.md, references/templates/config-example.md
related-skills: astro-content, astro-actions, astro-islands, astro-integrations, astro-deployment

<objective> Configures and explains Astro 7 (stable, 7.4.7) core framework mechanics: file-based routing, the two output modes (`static`/`server`) plus hybrid rendering via per-route `prerender`, middleware for auth/redirects/headers, the Vite Environment API, the single Rust compiler (Go compiler removed, strict HTML parsing), stable Content Security Policy, Live Content Collections, and the built-in Fonts API.

Covers initial project setup and migration from Astro 5/6, including breaking changes and Node 22.23.4+ requirements (the floor rose within Astro 7: 22.12 at 7.0, 22.22 at 7.4.0, 22.23.4 at 7.4.7). 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. </objective>

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

1. **fuse-ai-pilot:explore-codebase** - Analyze existing routes, layouts, and config 2. **fuse-ai-pilot:research-expert** - Verify latest Astro 7 docs via Context7/Exa 3. **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](references/installation.md) | | Routing patterns | [routing.md](references/routing.md) | | Output configuration | [output-modes.md](references/output-modes.md) | | Middleware setup | [middleware.md](references/middleware.md) | | astro.config.ts | [config.md](references/config.md) | | New Astro 7 features | [new-features.md](references/new-features.md) | | Full project setup | [templates/basic-setup.md](references/templates/basic-setup.md) | | Config examples | [templates/config-example.md](references/templates/config-example.md) |

---

Best Practices

1. **Use `output: 'static'` by default** — Add server only when needed 2. **Per-route `prerender`** — Fine-grained hybrid control (`output` only accepts `'static' | 'server'`; there is no `'hybrid'` value) 3. **Middleware for cross-cutting concerns** — Auth, redirects, headers 4. **No compiler flag needed** — the Rust compiler is the only compiler now (Go removed); watch for strict HTML parsing errors on unclosed tags 5. **CSP hashes** — Use built-in stable `security.csp` (hash-based, plus the `Astro.csp` runtime API) instead of custom headers 6. **Node 22.23.4+ required** (current floor per the install docs; Node 24/26 LTS are fine, odd-numbered versions are unsupported) — and keep `typescript` on 5.x/6.x: `@astrojs/check` 0.9.x peers `^5 || ^6`, so TypeScript 7 (`tsgo`, npm `latest`) is not supported by `astro check` (see installation.md)