astro-best-practiceslisted

# Astro: Core Architecture & Best Practices ## Core Philosophy Astro is content-first and ships ZERO JavaScript by default. Internalize this before writing any code. Assume every component renders as plain HTML unless interactivity is strictly necessary — only opt in to JavaScript through explicit client directives when state or event handling is required. Astro uses a Multi-Page Application (MPA) mindset, not a Single-Page Application (SPA) mindset. Do not attempt to replicate SPA patterns like global client-side state stores or full-page client-side routing unless explicitly asked. Understand the strict separation of environments: build-time (Content Layer fetches and transforms data), server-time (SSR endpoints, Server Islands, middleware), and browser-time (Client Islands, `<script>` tags). Never mix these boundaries. Data flows downward: build-time or server-time code produces HTML and passes serializable props to client components. The browser never calls `getCollection()` or accesses `Astro.locals`. ## Component Model Every `.astro` file has two regions: the frontmatter fence (`---`) and the template below it. The frontmatter is SERVER-ONLY code that runs at build time or request time. Use it to import components, fetch data, define variables, and destructure props. Never access `window`, `document`, `localStorage`, or any browser API in frontmatter — doing so causes `document is not defined` or `window is not defined` errors. Client-side JavaScript belongs in `<