Astro Server‑Only Components: Architecture, Checks, and When to Redesign

Problem Statement

When building an Astro site you often need to fetch data that should stay on the server—database queries, private API calls, or heavy calculations. Astro’s server directive lets you create components that run exclusively on the server, keeping the client bundle lean and protecting sensitive data. This note outlines the requirements for using server‑only components, the minimal design that satisfies those requirements, how to enforce trust and data boundaries, operational checks you should run, and the failure modes that would force you to rethink the architecture.

Requirements

• Server‑only execution – the component must never be hydrated or executed in the browser.
• Data isolation – all sensitive or heavy data must be fetched on the server and never exposed to client‑side JavaScript.
• Composable hierarchy – parent pages or components that render a server‑only child must also be server‑only (or have a server‑only ancestor).
• Clear prop contract – any data the component needs from the outside must be passed in as props; there is no implicit access to user input or browser state.
• Build‑time safety – attempting to use browser APIs (window, document, localStorage) inside a server‑only component should fail at build time.

Minimal Design

A minimal server‑only component follows this pattern:

---
//