Astro Web Framework
Übersicht
Astro ist ein Web-Framework für inhaltsreiche Websites – Blogs, Dokumentationen, Portfolios, Marketingseiten und E-Commerce. Seine Kerninnovation ist die Inselarchitektur: Standardmäßig liefert Astro null JavaScript an den Browser aus. Interaktive Komponenten werden selektiv als isolierte „Inseln“ hydriert. Astro unterstützt React, Vue, Svelte, Solid und andere UI-Frameworks gleichzeitig im selben Projekt, sodass du das richtige Werkzeug pro Komponente wählen kannst.
Wann dieses Skill verwendet werden sollte
- Verwende es beim Erstellen eines Blogs, einer Dokumentationsseite, einer Marketingseite oder eines Portfolios
- Verwende es, wenn Leistung und Core Web Vitals oberste Priorität haben
- Verwende es, wenn das Projekt viele Markdown- oder MDX-Dateien enthält
- Verwende es, wenn du SSG (statische) Ausgabe mit optionalem SSR für dynamische Routen wünschst
- Verwende es, wenn der Benutzer nach
.astro-Dateien,Astro.props, Content Collections oderclient:-Direktiven fragt
Wie es funktioniert
Schritt 1: Projekteinrichtung
npm create astro@latest my-site
cd my-site
npm install
npm run dev
Integrationen nach Bedarf hinzufügen:
npx astro add tailwind # Tailwind CSS
npx astro add react # React-Komponentenunterstützung
npx astro add mdx # MDX-Unterstützung
npx astro add sitemap # Automatische sitemap.xml
npx astro add vercel # Vercel SSR-Adapter
Projektstruktur:
src/
pages/ ← Dateibasiertes Routing (.astro, .md, .mdx)
layouts/ ← Wiederverwendbare Seitenrahmen
components/ ← UI-Komponenten (.astro, .tsx, .vue, usw.)
content/ ← Typsichere Content Collections (Markdown/MDX)
styles/ ← Globales CSS
public/ ← Statische Assets (werden unverändert kopiert)
astro.config.mjs ← Framework-Konfiguration
Schritt 2: Astro-Komponentensyntax
.astro-Dateien haben einen Code-Fence oben (nur server-seitig) und ein Template darunter:
---
// src/components/Card.astro
// Dieser Block wird NUR auf dem Server ausgeführt – niemals im Browser
interface Props {
title: string;
href: string;
description: string;
}
const { title, href, description } = Astro.props;
---
<article class="card">
<h2><a href={href}>{title}</a></h2>
<p>{description}</p>
</article>
<style>
/* Automatisch auf diese Komponente beschränkt */
.card { border: 1px solid #eee; padding: 1rem; }
</style>
Schritt 3: Dateibasierte Seiten und Routing
src/pages/index.astro → /
src/pages/about.astro → /about
src/pages/blog/[slug].astro → /blog/:slug (dynamisch)
src/pages/blog/[...path].astro → /blog/* (Auffangpfad)
Dynamische Route mit getStaticPaths:
---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map(post => ({
params: { slug: post.slug },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await post.render();
---
<h1>{post.data.title}</h1>
<Content />
Schritt 4: Content Collections
Content Collections bieten typsicheren Zugriff auf Markdown- und MDX-Dateien:
// src/content/config.ts
import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
date: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';
const posts = (await getCollection('blog'))
.filter(p => !p.data.draft)
.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---
<ul>
{posts.map(post => (
<li>
<a href={`/blog/${post.slug}`}>{post.data.title}</a>
<time>{post.data.date.toLocaleDateString()}</time>
</li>
))}
</ul>
Schritt 5: Inseln – Selektive Hydrierung
Standardmäßig rendern UI-Framework-Komponenten zu statischem HTML ohne JS. Verwende client:-Direktiven zur Hydrierung:
---
import Counter from '../components/Counter.tsx'; // React-Komponente
import VideoPlayer from '../components/VideoPlayer.svelte';
---
<!-- Statisches HTML – kein JavaScript an den Browser gesendet -->
<Counter initialCount={0} />
<!-- Sofort beim Laden der Seite hydrieren -->
<Counter initialCount={0} client:load />
<!-- Hydrieren, wenn die Komponente in den Viewport scrollt -->
<VideoPlayer src="/demo.mp4" client:visible />
<!-- Nur hydrieren, wenn der Browser im Leerlauf ist -->
<Analytics client:idle />
<!-- Nur bei einer bestimmten Media Query hydrieren -->
<MobileMenu client:media="(max-width: 768px)" />
Schritt 6: Layouts
---
// src/layouts/BaseLayout.astro
interface Props {
title: string;
description?: string;
}
const { title, description = 'My Astro Site' } = Astro.props;
---
<html lang="en">
<head>
<meta charset="utf-8" />
<title>{title}</title>
<meta name="description" content={description} />
</head>
<body>
<nav>...</nav>
<main>
<slot /> <!-- Seiteninhalt wird hier gerendert -->
</main>
<footer>...</footer>
</body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="About Us">
<h1>About Us</h1>
<p>Welcome to our company...</p>
</BaseLayout>
Schritt 7: SSR-Modus (On-Demand-Rendering)
Aktiviere SSR für dynamische Seiten durch Setzen eines Adapters:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'hybrid', // 'static' | 'server' | 'hybrid'
adapter: vercel(),
});
Optiere einzelne Seiten mit export const prerender = false in SSR um.
Beispiele
Beispiel 1: Blog mit RSS-Feed
// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
export async function GET(context) {
const posts = await getCollection('blog');
return rss({
title: 'My Blog',
description: 'Latest posts',
site: context.site,
items: posts.map(post => ({
title: post.data.title,
pubDate: post.data.date,
link: `/blog/${post.slug}/`,
})),
});
}
Beispiel 2: API-Endpunkt (SSR)
// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';
export const POST: APIRoute = async ({ request }) => {
const { email } = await request.json();
if (!email) {
return new Response(JSON.stringify({ error: 'Email required' }), {
status: 400,
headers: { 'Content-Type': 'application/json' },
});
}
await addToNewsletter(email);
return new Response(JSON.stringify({ success: true }), { status: 200 });
};
Beispiel 3: React-Komponente als Insel
// src/components/SearchBox.tsx
import { useState } from 'react';
export default function SearchBox() {
const [query, setQuery] = useState('');
const [results, setResults] = useState([]);
async function search(e: React.FormEvent) {
e.preventDefault();
const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
setResults(data);
}
return (
<form onSubmit={search}>
<input value={query} onChange={e => setQuery(e.target.value)} />
<button type="submit">Search</button>
<ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
</form>
);
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Sofort hydriert – diese Insel ist interaktiv -->
<SearchBox client:load />
Best Practices
- ✅ Behalte die meisten Komponenten als statische
.astro-Dateien – hydriere nur das, was interaktiv sein muss - ✅ Verwende Content Collections für alle Markdown/MDX-Inhalte – du erhältst Typsicherheit und automatische Validierung
- ✅ Bevorzuge
client:visiblegegenüberclient:loadfür Komponenten unterhalb der Falte, um anfängliches JS zu reduzieren - ✅ Verwende
import.meta.envfür Umgebungsvariablen – stelle öffentlichen VariablenPUBLIC_voran - ✅ Füge
<ViewTransitions />vonastro:transitionshinzu, um flüssige Seitennavigation ohne vollständiges SPA zu ermöglichen - ❌ Verwende
client:loadnicht bei jeder Komponente – dies hebt Astros Leistungsvorteil auf - ❌ Lege keine Geheimnisse im
.astro-Frontmatter ab, die in clientseitigen Templates verwendet werden - ❌ Überspringe
getStaticPathsnicht für dynamische Routen im statischen Modus – Builds schlagen fehl
Sicherheitshinweise
- Frontmatter-Code in
.astro-Dateien wird nur serverseitig ausgeführt und niemals an den Browser weitergegeben. - Verwende
import.meta.env.PUBLIC_*nur für nicht sensible Werte. Private Umgebungsvariablen (ohnePUBLIC_-Präfix) werden niemals an den Client gesendet. - Validiere im SSR-Modus alle
Astro.request-Eingaben vor Datenbankabfragen oder API-Aufrufen. - Bereinige alle benutzergenerierten Inhalte vor dem Rendern mit
set:html– es umgeht die automatische Maskierung.
Häufige Fallstricke
-
Problem: JavaScript einer React/Vue-Komponente wird im Browser nicht ausgeführt Lösung: Füge eine
client:-Direktive (client:load,client:visible, usw.) hinzu – ohne diese werden Komponenten nur als statisches HTML gerendert. -
Problem: Daten von
getStaticPathssind nach Inhaltsaktualisierungen während der Entwicklung veraltet Lösung: Astros Dev-Server überwacht Inhaltsdateien – starte ihn neu, wenn Änderungen ancontent/config.tsnicht berücksichtigt werden. -
Problem: Der Typ von
Astro.propsistany– keine Autovervollständigung Lösung: Definiere einProps-Interface oder einen Typen im Frontmatter, und Astro leitet ihn automatisch ab. -
Problem: CSS einer
.astro-Komponente beeinflusst andere Komponenten Lösung: Styles innerhalb von.astro-<style>-Tags werden automatisch beschränkt. Verwende:global()nur, wenn du absichtlich Kindelemente ansprechen möchtest.
Verwandte Skills
@sveltekit– Wenn du ein Full-Stack-Framework mit reaktiver UI benötigst (im Gegensatz zu Astros Inhaltsfokus)@nextjs-app-router-patterns– Wenn du ein React-zentriertes Full-Stack-Framework benötigst@tailwind-patterns– Gestaltung von Astro-Seiten mit Tailwind CSS@progressive-web-app– Hinzufügen von PWA-Funktionen zu einer Astro-Seite
Einschränkungen
- Verwende dieses Skill nur, wenn die Aufgabe eindeutig dem oben beschriebenen Anwendungsbereich entspricht.
- Betrachte die Ausgabe nicht als Ersatz für umgebungsspezifische Validierung, Tests oder Expertenüberprüfung.
- Halte inne und bitte um Klärung, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.