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');
---

<!-- Component template -->
<html>
  <head><title>{title}</title></head>
  <body>
    <Header />
    <main>
      <slot />
    </main>
    <!-- Island: hydrates on client -->
    <ReactCounter client:load />
  </body>
</html>

<style>
  main { max-width: 800px; }
</style>

Client Directives (Islands)

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' });
---

<Image
  src={heroImage}
  alt="Hero"
  widths={[400, 800, 1200]}
  sizes="(max-width: 800px) 100vw, 800px"
  loading="eager"
/>

<!-- Lazy hydration for islands -->
<ReactWidget client:visible />

<!-- View Transitions -->
<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

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

Quick Troubleshooting

Reference Documentation

• Islands Architecture
• Content Collections