astro-best-practices

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 <script> tags in the template section, not in frontmatter. Astro processes <script> tags and bundles them automatically. Use <script> for DOM manipulation, event listeners, and browser API access.

For props, always destructure Astro.props with sensible defaults so components work without every prop being passed. Collect remaining attributes with ...attrs and spread them on the root element to allow consumers to pass id, aria-*, data-*, and class attributes freely. Use class:list for dynamic class composition — it accepts strings, arrays, objects, and variables. Import HTMLAttributes from astro/types and extend your Props interface for full editor autocompletion: