Astro Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: astro for comprehensive documentation.

Component Structure

// Component script (runs at build time) import Header from '../components/Header.astro'; import ReactCounter from '../components/Counter.tsx';

const { title } = Astro.props; const posts = await Astro.glob('./posts/*.md');

<html> <head><title>{title}</title></head> <body> <Header /> <main> <slot /> </main>  <ReactCounter client:load /> </body> </html>

Client Directives (Islands)

Directive Behavior

client:load

Hydrate immediately

client:idle

Hydrate when idle

client:visible

Hydrate when visible

client:media

Hydrate on media query

client:only

Skip SSR, client only

Content Collections

// src/content/config.ts import { defineCollection, z } from 'astro:content';

const blog = defineCollection({ type: 'content', schema: z.object({ title: z.string(), date: z.date(), draft: z.boolean().default(false), }), });

export const collections = { blog };

import { getCollection } from 'astro:content'; const posts = await getCollection('blog', ({ data }) => !data.draft);

Key Features

Zero JS by default (ship HTML)
Use React, Vue, Svelte together
Content collections with type safety
Built-in Markdown/MDX support

Production Readiness

Security Configuration

// astro.config.mjs import { defineConfig } from 'astro/config';

export default defineConfig({ security: { checkOrigin: true, // CSRF protection for SSR }, vite: { define: { // Never expose secrets to client 'import.meta.env.SECRET_KEY': 'undefined', }, }, });

// src/middleware.ts import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => { const response = await next();

// Security headers response.headers.set('X-Frame-Options', 'DENY'); response.headers.set('X-Content-Type-Options', 'nosniff'); response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin'); response.headers.set( 'Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'" );

return response; });

Content Validation

// src/content/config.ts import { defineCollection, z, reference } from 'astro:content';

const blog = defineCollection({ type: 'content', schema: ({ image }) => z.object({ title: z.string().max(100), description: z.string().max(200), date: z.date(), author: reference('authors'), cover: image().refine((img) => img.width >= 800, { message: 'Cover image must be at least 800px wide', }), tags: z.array(z.string()).max(5), draft: z.boolean().default(false), }), });

export const collections = { blog };

Performance

// astro.config.mjs import { defineConfig } from 'astro/config'; import compress from 'astro-compress'; import sitemap from '@astrojs/sitemap';

export default defineConfig({ site: 'https://example.com', integrations: [ sitemap(), compress({ CSS: true, HTML: true, Image: true, JavaScript: true, SVG: true, }), ], build: { inlineStylesheets: 'auto', }, prefetch: { prefetchAll: true, defaultStrategy: 'viewport', }, });

// Image optimization import { Image, getImage } from 'astro:assets'; import heroImage from '../assets/hero.png';

const optimizedBackground = await getImage({ src: heroImage, format: 'webp' });

<ReactWidget client:visible />

<ViewTransitions />

Error Handling

// src/pages/404.astro import Layout from '../layouts/Layout.astro';

<Layout title="Page Not Found"> <div class="error-page"> <h1>404</h1> <p>Page not found</p> <a href="/">Go home</a> </div> </Layout>

// src/pages/500.astro import Layout from '../layouts/Layout.astro';

<Layout title="Server Error"> <div class="error-page"> <h1>500</h1> <p>Something went wrong</p> <a href="/">Go home</a> </div> </Layout>

// src/pages/api/data.ts import type { APIRoute } from 'astro';

export const GET: APIRoute = async ({ request }) => { try { const data = await fetchData(); return new Response(JSON.stringify(data), { status: 200, headers: { 'Content-Type': 'application/json' }, }); } catch (error) { console.error('API error:', error); return new Response(JSON.stringify({ error: 'Internal server error' }), { status: 500, headers: { 'Content-Type': 'application/json' }, }); } };

Testing

// tests/e2e/blog.spec.ts import { test, expect } from '@playwright/test';

test.describe('Blog', () => { test('lists published posts', async ({ page }) => { await page.goto('/blog');

const posts = page.locator('article');
await expect(posts).toHaveCount(await posts.count());
await expect(posts.first()).toBeVisible();

});

test('navigates to post', async ({ page }) => { await page.goto('/blog'); await page.click('article a');

await expect(page.locator('h1')).toBeVisible();
await expect(page).toHaveURL(/\/blog\/.+/);

}); });

// Component testing with container queries test('island hydrates on visibility', async ({ page }) => { await page.goto('/');

const counter = page.locator('[data-testid="counter"]'); await expect(counter).not.toBeVisible();

await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); await expect(counter).toBeVisible(); });

Deployment Configuration

Vercel - vercel.json

{ "buildCommand": "astro build", "outputDirectory": "dist", "framework": "astro" }

Netlify - netlify.toml

[build] command = "astro build" publish = "dist"

Docker

FROM node:20-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build

FROM nginx:alpine COPY --from=build /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/nginx.conf EXPOSE 80

Monitoring Metrics

Metric Target

Lighthouse Score

95

First Contentful Paint < 1s

Time to Interactive < 1.5s

Total Blocking Time < 50ms

Bundle size (JS) < 50KB

Checklist

Security headers in middleware
checkOrigin enabled for SSR
Content collections with Zod schemas
Image optimization with astro:assets
Lazy hydration (client:visible/idle)
View Transitions enabled
404/500 error pages
Sitemap generation
Asset compression
E2E tests with Playwright
Lighthouse CI in pipeline

When NOT to Use This Skill

This skill is for Astro (content-focused, islands architecture). DO NOT use for:

Next.js (React meta-framework): Use nextjs-app-router skill instead
Nuxt (Vue meta-framework): Use nuxt3 skill instead
SvelteKit (Svelte meta-framework): Use sveltekit skill instead
Remix (React meta-framework): Use remix skill instead
Pure React applications: Use frontend-react skill instead
Pure Vue applications: Use frontend-vue skill instead
Pure Svelte applications: Use frontend-svelte skill instead
Gatsby: Astro is a modern alternative, but migration differs

Anti-Patterns

Anti-Pattern Why It's Wrong Correct Approach

Using client:load everywhere Defeats zero-JS philosophy, large bundles Use client:idle or client:visible for deferred hydration

Not using content collections Unvalidated content, no type safety Define collections in src/content/config.ts

Mixing frameworks unnecessarily Increases bundle size, complexity Use one framework per project, or Astro components

Ignoring image optimization Poor performance, large assets Use from astro:assets

Not setting alt text on images Accessibility issue, SEO penalty Always provide meaningful alt text

Using client:only for all content No SSR, poor SEO Use client:only only for browser-only components

Hardcoding data in components Unmaintainable, no CMS integration Use content collections or API fetching

No ViewTransitions Choppy navigation UX Add to layout

Quick Troubleshooting

Issue Possible Cause Solution

"Cannot use import.meta.env in client" Accessing server-only env var Prefix with PUBLIC_ for client access

Island not hydrating Wrong client directive Check client:load/idle/visible directive is set

Content collection not found Schema not defined or wrong path Define in src/content/config.ts, check src/content/{collection}

Images not optimized Using instead of Import and use from astro:assets

"getCollection is not defined" Wrong import Import from 'astro:content'

Build fails with type errors Content schema mismatch Check frontmatter matches Zod schema

404 page not showing Missing src/pages/404.astro Create 404.astro in src/pages/

CSS not scoped Missing in component Add block to Astro component

Reference Documentation

Islands Architecture
Content Collections

astro

Safety Notice

Copy this and send it to your AI assistant to learn

const { title } = Astro.props; const posts = await Astro.glob('./posts/*.md');

import { getCollection } from 'astro:content'; const posts = await getCollection('blog', ({ data }) => !data.draft);

const optimizedBackground = await getImage({ src: heroImage, format: 'webp' });

// src/pages/404.astro import Layout from '../layouts/Layout.astro';

// src/pages/500.astro import Layout from '../layouts/Layout.astro';

Vercel - vercel.json

Netlify - netlify.toml

Docker

Source Transparency

Related Skills

astro-developer

cron-scheduling

token-optimization