astro-expert

astro-expert

Expert knowledge for building production-ready frontends with Astro — combining static rendering, selective hydration, and React islands for interactive components.

1) Core Architecture Principles

• Islands architecture: static Astro shell + selectively hydrated React islands
• Zero JS by default — every kilobyte of hydrated JS must justify itself with UX value
• client:load — hydrate immediately (forms, critical interactivity)
• client:idle — hydrate when browser is idle (non-critical widgets)
• client:visible — hydrate when in viewport (below-the-fold islands)
• client:only="react" — skip SSR entirely for fully client-driven components (SSE consumers, real-time UIs)

2) Project Structure

src/
├── layouts/          # Astro layout shells (zero JS)
├── pages/            # File-based routing (.astro files)
│   └── [id].astro    # Dynamic segments
├── components/
│   ├── layout/       # Pure Astro layout primitives
│   ├── ui/           # Shared React primitives (Button, Card, Badge)
│   └── features/     # React islands — business-logic components
├── lib/              # Utilities, API client, hooks
│   ├── utils.ts      # cn() helper, formatters
│   ├── api.ts        # Backend API client
│   └── useEventStream.ts  # SSE hook
├── styles/
│   ├── tokens.css    # CSS custom properties (color, spacing, radius)
│   └── app.css       # Tailwind entry + base overrides
└── types/            # Shared TypeScript interfaces

3) Configuration Baseline

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [
    react(),
    tailwind({ applyBaseStyles: false }),
  ],
  output: 'hybrid', // static by default, opt-in SSR per page
});

Mark dynamic pages: export const prerender = false;

4) React Island Pattern

---
// pages/projects/[id].astro — static shell
import BaseLayout from '@/layouts/BaseLayout.astro';
import PipelineStream from '@/components/features/PipelineStream';

const { id } = Astro.params;
---
<BaseLayout title="Project">
  <!-- client:only skips SSR — needed for SSE hooks -->
  <PipelineStream projectId={id} client:only="react" />
</BaseLayout>