Astro Component Pattern

Astro Component Pattern

The .astro file format — server-only frontmatter, HTML-like templates, and scoped CSS — is the foundation of every Astro project.

When to Use

• You are creating a new UI component that does not require client-side interactivity
• You need to fetch data at request/build time and render it as static HTML
• You want CSS that is automatically scoped to the component without a CSS module setup
• You are building layouts, pages, or reusable UI fragments in an Astro project
• You need to understand the anatomy of .astro files before working with islands, routing, or content collections

Instructions

1. Structure every .astro file with three sections in order: frontmatter script, template, and optional <style>:

---
// 1. Frontmatter (runs server-side only — never sent to the browser)
import OtherComponent from './OtherComponent.astro';
import type { Props } from './types';

interface Props {
  title: string;
  description?: string;
  variant?: 'primary' | 'secondary';
}

const { title, description = 'No description', variant = 'primary' } = Astro.props;
const formattedDate = new Date().toLocaleDateString('en-US');
---

<!-- 2. Template (JSX-like but compiles to plain HTML) -->
<article class={`card card--${variant}`}>
  <h2>{title}</h2>
  <p>{description}</p>
  <OtherComponent date={formattedDate} />
</article>

<!-- 3. Scoped styles (automatically namespaced — no class collisions) -->
<style>
  .card {
    border: 1px solid var(--color-border);
    padding: 1rem;
  }
  .card--primary { background: var(--color-surface); }
  .card--secondary { background: var(--color-muted); }
</style>

2. Declare Props as a TypeScript interface inside the frontmatter. Astro reads this interface to provide type-safe props at the call site.

3. Destructure props from Astro.props. The Astro global is available in every .astro file — it also provides Astro.url, Astro.site, Astro.request, Astro.cookies, Astro.redirect(), and Astro.locals.

4. Use <slot /> to render child content passed between component tags. Named slots handle multiple content areas:

<!-- Layout.astro -->
<header><slot name="header" /></header>
<main><slot /></main>  <!-- default slot -->
<footer><slot name="footer" /></footer>

<!-- Usage -->
<Layout>
  <h1 slot="header">Page Title</h1>
  <p>Main content goes in the default slot.</p>
  <p slot="footer">Footer text</p>
</Layout>

5. Apply is:global to override scoped styles when you must style child component internals or third-party HTML:

<style is:global>
  /* Applies globally — use sparingly */
  .prose h2 { margin-top: 2rem; }
</style>

6. Use define:vars to pass frontmatter variables into scoped CSS as custom properties:

---
const accentColor = '#ff6b35';
---
<div class="hero">Hero section</div>
<style define:vars={{ accentColor }}>
  .hero { background: var(--accentColor); }
</style>

7. Use template expressions for conditional rendering and iteration:

<!-- Conditional -->
{isLoggedIn && <UserMenu />}
{isLoggedIn ? <UserMenu /> : <LoginButton />}

<!-- Iteration -->
{items.map((item) => (
  <li key={item.id}>{item.name}</li>
))}

<!-- Fragments (no wrapper element) -->
<>
  <dt>{term}</dt>
  <dd>{definition}</dd>
</>

8. Never write import statements inside the template section. All imports and logic belong in the frontmatter fence.

Details

The .astro format is superficially similar to JSX but has a fundamental difference: the frontmatter runs exclusively on the server (or at build time). It never reaches the browser. This means you can safely use Node.js APIs, read files, query databases, and import server-only packages in the frontmatter fence.

Scoped styles explained:

Astro transforms scoped <style> blocks by adding a unique data attribute (e.g., data-astro-cid-xyz) to every element the component renders and scoping the CSS to that attribute. This prevents style leakage without requiring CSS Modules or a naming convention. The compiled CSS is extracted and bundled separately — it does not live inline in the HTML.

Template differences from JSX:

• Use class not className (Astro is HTML, not React)
• set:html instead of dangerouslySetInnerHTML: <p set:html={rawHtml} />
• is:raw on code blocks to prevent Astro from processing curly braces inside
• Expressions are wrapped in {} and must be single expressions — no multi-statement blocks in the template

Performance characteristics:

.astro components have zero runtime overhead. They compile to static HTML strings at build time (SSG) or at request time (SSR). No virtual DOM, no reconciliation, no hydration cost. A page made entirely of .astro components ships exactly 0 bytes of JavaScript.

When to reach for a framework component instead:

Use .astro for everything that does not need onClick, useState, or any browser-only API. When interactivity is required, create a React/Vue/Svelte component and import it into the .astro file with a client:* directive. The .astro wrapper remains server-rendered; only the framework component hydrates.

Layouts:

Layouts are .astro components that use <slot /> to wrap page content. They live in src/layouts/ by convention. A layout component wraps page-level structure (<html>, <head>, <body>) and injects page-specific content via slots. Astro does not enforce a special layout mechanism — layouts are just components with slots.

Source

https://docs.astro.build/en/basics/astro-components

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.