astro

Astro Best Practices

Overview

Aspect	Recommendation
Use Case	Content-focused sites, blogs, docs
Default	Zero JS shipped to client
Interactive	Islands (React, Vue, Svelte, etc.)
Content	Content Collections

---

Project Structure

src/
├── components/     # .astro and framework components
├── content/        # Content collections (markdown, MDX)
│   └── blog/
│       └── post-1.md
├── layouts/        # Page layouts
├── pages/          # File-based routing
│   ├── index.astro
│   └── blog/
│       └── [slug].astro
├── styles/         # Global styles
└── content.config.ts  # Collection schemas

---

Astro Components

Basic Component

---
// Component Script (runs at build time)
interface Props {
  title: string
  description?: string
}

const { title, description = 'Default description' } = Astro.props
const currentYear = new Date().getFullYear()
---

<!-- Component Template -->
<article>
  <h1>{title}</h1>
  <p>{description}</p>
  <footer>© {currentYear}</footer>
</article>

<style>
  /* Scoped by default */
  article {
    padding: 1rem;
  }
</style>

Slots

---
// Card.astro
interface Props {
  title: string
}

const { title } = Astro.props
---

<div class="card">
  <h2>{title}</h2>
  <slot />  <!-- Default slot -->
  <slot name="footer" />  <!-- Named slot -->
</div>

<!-- Usage -->
<Card title="My Card">
  <p>Card content</p>
  <div slot="footer">Footer content</div>
</Card>

---

Islands Architecture

Client Directives

---
import ReactCounter from './Counter.tsx'
import VueModal from './Modal.vue'
---

<!-- Load immediately -->
<ReactCounter client:load />

<!-- Load when visible (lazy) -->
<ReactCounter client:visible />

<!-- Load when idle -->
<ReactCounter client:idle />

<!-- Load on specific media query -->
<VueModal client:media="(max-width: 768px)" />

<!-- Only hydrate client-side (no SSR) -->
<ReactCounter client:only="react" />