Astro Framework Skill
Conventions for building content-focused, high-performance websites with Astro.
When to Use
- •Creating or modifying
.astrocomponents - •Working with content collections (blog, docs)
- •Configuring Astro routing and layouts
- •Optimizing performance with island architecture
- •Integrating Vue components as islands
Critical Patterns
1. Island Architecture - Server First
ALWAYS minimize client-side JavaScript. Astro ships zero JS by default.
Compare these patterns: Static vs Interactive
Static component – No JavaScript shipped to the client:
--- import Header from '../components/Header.astro'; --- <Header title="Welcome" />
Interactive island – JavaScript loaded only for this component (uses client:visible):
--- import Counter from '../components/Counter.vue'; --- <Counter client:visible />
2. Hydration Directives
| Directive | When to Use |
|---|---|
client:load | Critical interactivity needed immediately |
client:idle | Non-critical, can wait for browser idle |
client:visible | Below the fold, hydrate on scroll |
client:media="(max-width: 768px)" | Mobile-only interactivity |
client:only="vue" | No SSR, client-only rendering (see note) |
Default choice: client:visible unless there's a reason otherwise.
[!WARNING]
client:onlytrade-offs Components usingclient:onlyskip server-side rendering entirely, which increases the client JS payload and can harm SEO since no HTML is rendered initially. Use only for:
- •Third-party widgets that cannot render on the server
- •Complex client-only UI (e.g., canvas, WebGL, maps)
- •Non-SEO-critical parts of the page (modals, admin dashboards)
For SEO-critical content, prefer
client:visibleorclient:idleto ensure initial HTML is crawlable.
3. Component Structure
Props typing options: Astro supports both runtime access via Astro.props and compile-time
typing.
Option 1: Type alias with Astro.props (runtime access)
---
// 1. Type definitions FIRST
type Props = {
title: string;
description?: string;
isActive?: boolean;
};
// 2. Props destructuring with defaults (runtime access)
const { title, description, isActive = false } = Astro.props;
// 3. Imports and logic
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
Option 2: Interface with typed component parameters (compile-time)
---
// Using interface for explicit typing
interface Props {
title: string;
description?: string;
isActive?: boolean;
}
// Type-checked at compile time
const { title, description, isActive = false }: Props = Astro.props;
---
Note: Both approaches are valid.
type Propsandinterface Propswork identically for component prop typing. The interface pattern is preferred when extending or merging types.
---
// Full example with imports and logic
type Props = {
title: string;
description?: string;
isActive?: boolean;
};
const { title, description, isActive = false } = Astro.props;
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
---
<!-- 4. Template -->
<section class:list={["hero", { active: isActive }]}>
<h1>{title}</h1>
{description && <p>{description}</p>}
<slot />
</section>
<!-- 5. Scoped styles -->
<style>
.hero {
padding: var(--space-8);
}
</style>
4. Content Collections
ALWAYS define schemas for type safety:
// src/content/config.ts
import {defineCollection, z} from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
description: z.string(),
publishDate: z.coerce.date(),
author: z.string(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = {blog};
5. Image Optimization
ALWAYS use Astro's Image component:
---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---
<!-- ✅ Optimized, responsive -->
<Image
src={heroImage}
alt="Hero banner"
width={1200}
height={600}
format="webp"
/>
<!-- ❌ NEVER use raw img for local images -->
<img src="/hero.jpg" alt="Hero" />
Project Structure (This Project)
client/apps/{marketing,blog}/
├── src/
│ ├── pages/ # File-based routing
│ ├── components/ # .astro and Vue components
│ ├── layouts/ # BaseLayout.astro, etc.
│ ├── content/ # Collections (blog posts, docs)
│ └── styles/ # Global CSS
├── public/ # Static assets
└── astro.config.mjs
Anti-Patterns
❌ Shipping unnecessary JS - Use .astro for static content
❌ Using client:load everywhere - Most components don't need immediate hydration
❌ Raw <img> tags - Use <Image> for optimization
❌ Inline styles for everything - Use scoped <style> blocks
❌ Hardcoded meta tags - Use a reusable BaseHead.astro
SEO Pattern
---
// BaseHead.astro
type Props = {
title: string;
description: string;
image?: string;
};
const { title, description, image } = Astro.props;
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="canonical" href={canonicalURL} />
<title>{title}</title>
<meta name="description" content={description} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:url" content={canonicalURL} />
{image && <meta property="og:image" content={new URL(image, Astro.site)} />}
Commands
Astro CLI Usage: The Astro CLI is not installed globally in this workspace. Use
pnpm exec astro(orpnpm --filter <pkg> exec astro) to run Astro-specific commands within the monorepo.
# Development pnpm --filter @cvix/marketing dev pnpm --filter @cvix/blog dev # Build pnpm --filter @cvix/marketing build pnpm --filter @cvix/blog build # Preview production build pnpm --filter @cvix/marketing preview # Running Astro CLI commands directly pnpm --filter @cvix/marketing exec astro check # Type-check .astro files pnpm --filter @cvix/blog exec astro add vue # Add integrations pnpm exec astro --help # View available commands
Integration with Vue
When using Vue components as islands:
---
import InteractiveWidget from '../components/InteractiveWidget.vue';
---
<!-- Pass props, use appropriate hydration -->
<InteractiveWidget
client:visible
title="Dashboard"
:items={data.items}
/>