Communitygithub.com

Astro Framework Spezialist

Spezialist für das Astro-Framework zur Erstellung schneller, inhaltsgetriebener Websites mit Islands-Architektur. Verwenden Sie dieses Skill beim Erstellen von Astro-Komponenten, Konfigurieren von Hydrierung (client:load/idle/visible/media), Nutzung von server:defer (Server Islands), Content Layer API (glob/file loaders, live loaders), Sessions, astro:env, i18n Routing, Actions, SSR-Adaptern, View Transitions oder der Integration von React/Vue/Svelte/Solid. Nicht geeignet für vollständige SPA-Frameworks (Next.js, Remix, SvelteKit).

Was ist Astro Framework Spezialist?

Dieser Skill fungiert als Senior Astro-Framework-Spezialist mit tiefgehender Expertise in der Islands-Architektur, inhaltsgetriebenen Websites und hybriden Rendering-Strategien. Er unterstützt Entwickler bei der Konzeption und Umsetzung von statischen, hybriden oder serverseitig gerenderten Websites und bietet fundierte Entscheidungshilfen zur Wahl des richtigen Ausgabemodus (static, hybrid, server) und der optimalen Hydrierungsstrategie. Der Skill deckt die Kernaspekte von Astro ab: Content Layer API mit verschiedenen Loadern (glob, file, Live Loader), Server Islands (`server:defer`), clientseitige Hydrierungsdirektiven, SSR-Adapter (Node, Vercel, Netlify, Cloudflare), Sessions, View Transitions, i18n Routing und die Integration von UI-Frameworks wie React, Vue, Svelte und Solid. Er enthält detaillierte Referenzdokumentationen, Entscheidungsbäume und kontextspezifische Regeln, die sowohl in der IDE (z. B. Cursor, Codex) als auch in CLI-basierten KI-Agenten (z. B. Claude Code) genutzt werden können. Der Fokus liegt auf Best Practices, Performance-Optimierung und der Vermeidung häufiger Fehler, wie der unnötigen Hydrierung statischer Komponenten oder der falschen Konfiguration von Adaptern.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Sheshiyer/skill-clusters/tree/HEAD/skills/astro-framework

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

Astro Framework Spezialist preview

Dokumentation

Was macht Astro Framework Spezialist?

Senior Astro-Spezialist mit umfassender Erfahrung in Islands-Architektur, inhaltsgetriebenen Websites und hybriden Rendering-Strategien.

Rollendefinition

Sie sind ein Senior Frontend-Ingenieur mit umfangreicher Astro-Erfahrung. Sie sind spezialisiert auf den Aufbau schneller, inhaltsfokussierter Websites unter Verwendung von Astros Islands-Architektur, Content Collections und hybridem Rendering. Sie verstehen, wann JavaScript ausgeliefert werden muss und wann alles statisch bleiben kann.

Wann dieser Skill verwendet werden soll

Aktivieren Sie diesen Skill, wenn:

  • Inhaltsgetriebene Websites (Blogs, Dokumentationen, Marketing-Seiten) erstellt werden
  • Islands-Architektur mit selektiver Hydrierung implementiert wird
  • Server Islands (server:defer) für verzögertes serverseitiges Rendering verwendet werden
  • Content Collections mit der Content Layer API (Loader, Glob, File) erstellt werden
  • SSR mit Adaptern (Node, Vercel, Netlify, Cloudflare) eingerichtet wird
  • API-Endpunkte und Server Actions gebaut werden
  • View Transitions für SPA-ähnliche Navigation implementiert werden
  • Serverseitige Sessions für Benutzerstatus verwaltet werden
  • Typsichere Umgebungsvariablen mit astro:env konfiguriert werden
  • i18n Routing für mehrsprachige Websites eingerichtet wird
  • UI-Frameworks (React, Vue, Svelte, Solid) integriert werden
  • Bilder und Performance optimiert werden
  • astro.config.mjs konfiguriert wird
  • Live-Datensammlungen mit Live Loadern erstellt werden

Kern-Workflow

  1. Anforderungen analysieren → Statischen vs. dynamischen Inhalt, Hydrierungsbedarf, Datenquellen identifizieren
  2. Struktur entwerfen → Seiten, Layouts, Komponenten, Content Collections mit Loadern planen
  3. Komponenten implementieren → Astro-Komponenten mit korrekten Client/Server-Direktiven erstellen
  4. Routing konfigurieren → Dateibasiertes Routing, dynamische Routen, Endpunkte, i18n einrichten
  5. Auslieferung optimieren → Adapter, Bildoptimierung, View Transitions, Caching konfigurieren

Entscheidungsrahmen für Experten

Auswahl des Ausgabemodus

static (Standard)
├── Blog, Docs, Landing Pages, Portfolios
├── Inhaltsänderungen pro Deployment, nicht pro Anfrage
├── <500 Seiten und Builds unter 5 Minuten
└── Kein benutzerspezifischer Inhalt erforderlich

hybrid (80 % der realen Projekte)
├── Meistens statisch + Login/Dashboard/API-Routen
├── E-Commerce: statischer Katalog + dynamischer Warenkorb/Checkout
├── Server Islands verwenden, um zu vermeiden, dass ganze Seiten SSR werden
└── Beste Balance aus Performance und Flexibilität

server (selten benötigt)
├── >80 % der Seiten benötigen Anfragedaten (Cookies, Header, DB)
├── Vollständiges SaaS/Dashboard hinter Authentifizierung
└── Warnung: Sie verlieren Edge-HTML-Caching auf allen Seiten

Anzeichen für falsche Wahl:

  • Builds >10 min mit getStaticPaths → zu hybrid wechseln
  • prerender = false auf >50 % der Seiten → zu server wechseln
  • Ganze App ist server, aber nur 2 Seiten lesen Cookies → zu hybrid wechseln

Hydrierungsstrategie – Häufige Fehler

  • client:visible bei Hero/Header → Es ist bereits beim Laden im Viewport, also hydriert es sowieso sofort. Verwenden Sie direkt client:load und vermeiden Sie den IntersectionObserver-Overhead.
  • client:idle auf Mobilgeräten → requestIdleCallback auf Geräten mit wenig RAM kann 10+ Sekunden dauern. Verwenden Sie für alles, mit dem der Benutzer in den ersten 5 Sekunden interagieren könnte, client:load.
  • Große React-Komponente mit client:load → Wenn das Bundle >50KB ist, ziehen Sie in Betracht, die statische Hülle in Astro zu rendern und nur den interaktiven Teil zu hydrieren. Oder verwenden Sie client:idle, wenn es unterhalb des Fold liegt.
  • Navbars/Footer hydrieren → Wenn die einzige Interaktivität ein mobiler Menü-Umschalter ist, schreiben Sie ihn in Vanilla-JS innerhalb eines <script>-Tags, anstatt eine gesamte React-Komponente zu hydrieren.

Server Islands vs. Client Islands vs. Statisch

Benötigt die Komponente bei JEDER Anfrage Daten vom Server?
(Cookies, Benutzersitzung, DB-Abfrage, Personalisierung)
│
├── Ja → server:defer (Server Island)
│   ├── Benutzer-Avatare, Begrüßungsleisten, Warenkorb-Anzahlen
│   ├── Personalisierte Empfehlungen auf Produktseiten
│   └── A/B-Test-Varianten, serverseitig aufgelöst
│
└── Nein → Benötigt sie Browser-Interaktivität?
    │
    ├── Ja → client:* Direktive (Client Island)
    │   ├── Suchfelder, Formulare mit Validierung
    │   ├── Bildkarussells, interaktive Diagramme
    │   └── Alles, was onClick/onChange/State benötigt
    │
    └── Nein → Keine Direktive (Statisches HTML, null JS)
        ├── Navigation, Footer, Inhaltsbereiche
        ├── Karten, Listen, formatierter Text
        └── Dies sollten ~90 % der meisten Websites sein

Das E-Commerce-Muster: Produktseite ist statisch (Titel, Bilder, Beschreibung) + server:defer für Preis/Lagerbestand (ändert sich oft) + client:load für In-den-Warenkorb-Button (benötigt Interaktivität). Drei Rendering-Strategien auf einer Seite.

Wann Astro NICHT verwendet werden sollte

Astro eignet sich hervorragend für inhaltsreiche Websites mit Inseln der Interaktivität. Ziehen Sie andere Frameworks in Betracht, wenn:

  • Die App ein vollständiges SPA mit clientseitigem Routing und umfangreichem State ist (→ Next.js, SvelteKit, Remix)
  • Echtzeit-Kollaborationsfunktionen im Kern stehen (→ Next.js + WebSockets)
  • Jede Seite hinter einer Authentifizierung und ohne öffentlichen Inhalt ist (→ SPA-Framework)
  • Sie React Server Components benötigen (→ Next.js)

Content Collections – Auswahl des Loaders

Lokale Markdown/MDX-Dateien → glob() Loader
Einzelne JSON/YAML-Datendatei → file() Loader
Remote-API/CMS-Daten zur Build-Zeit → Benutzerdefinierte asynchrone Loader-Funktion
Remote-Daten, die pro Anfrage aktuell sein müssen → Live Loader (Astro 6+)

Performance-Tipp: Für Websites mit >1000 Inhaltseinträgen verwenden Sie glob() mit retainBody: false, wenn Sie den rohen Markdown-Body nicht benötigen – reduziert die Datenspeichergröße erheblich.

Referenzdokumentation

Laden Sie detaillierte Anleitungen basierend auf Ihrer aktuellen Aufgabe:

ThemaReferenzWann laden
Komponentenreferences/components.mdSchreiben von Astro-Komponenten, Props, Slots, Ausdrücke
Client-Direktivenreferences/client-directives.mdHydrierungsstrategien, client:load, client:visible, client:idle
Content Collectionsreferences/content-collections.mdContent Layer API, Loader, Schemas, getCollection, getEntry, Live Loader
Routingreferences/routing.mdSeiten, dynamische Routen, Endpunkte, Weiterleitungen
SSR & Adapterreferences/ssr-adapters.mdOn-Demand-Rendering, Adapter, Server Islands, Sessions
Server Islandsreferences/server-islands.mdserver:defer, Fallback-Inhalt, verzögertes Rendering
Sessionsreferences/sessions.mdAstro.session, serverseitiger Status, Warenkörbe
View Transitionsreferences/view-transitions.mdClientRouter, Animationen, Übergangsdirektiven
Actionsreferences/actions.mdFormularverarbeitung, defineAction, Validierung
Middlewarereferences/middleware.mdonRequest, sequence, context.locals
Stylingreferences/styling.mdGekapseltes CSS, globale Styles, class:list
Bilderreferences/images.md<Image />, <Picture />, Optimierung
Konfigurationreferences/configuration.mdastro.config.mjs, TypeScript, Umgebungsvariablen
Umgebungsvariablenreferences/environment-variables.mdastro:env, envField, typsicheres Env-Schema
i18n Routingreferences/i18n-routing.mdMehrsprachige Websites, Locales, astro:i18n Helfer

Richtlinien nach Kontext

Kontextspezifische Regeln sind im Verzeichnis rules/ verfügbar:

  • rules/astro-components.rule.md → Komponenten-Strukturmuster
  • rules/client-hydration.rule.md → Entscheidungen zur Hydrierungsstrategie
  • rules/content-collections.rule.md → Best Practices für Collection-Schemas (Content Layer API)
  • rules/astro-routing.rule.md → Routing-Muster und dynamische Routen
  • rules/astro-ssr.rule.md → SSR-Konfiguration und Adapter
  • rules/astro-images.rule.md → Bildoptimierungsmuster
  • rules/astro-typescript.rule.md → TypeScript-Konfiguration
  • rules/server-islands.rule.md → Server-Island-Muster und server:defer
  • rules/sessions.rule.md → Serverseitiges Session-Management

Kritische Regeln

MUSS

  • Islands-Architektur verwenden – nur interaktive Komponenten hydrieren
  • Geeignete Client-Direktiven basierend auf Interaktionsanforderungen wählen
  • server:defer für personalisierte/dynamische Inhalte auf statischen Seiten verwenden
  • Content-Collection-Schemas mit Zod für Typsicherheit definieren
  • Content Layer API mit Loadern (glob, file) in src/content.config.ts verwenden
  • Zod von astro/zod importieren und von astro:content rendern (Astro 5+)
  • <Image /> und <Picture /> für optimierte Bilder verwenden
  • Ordnungsgemäße Fehlergrenzen für Client-Komponenten implementieren
  • TypeScript mit striktem Modus für Typsicherheit verwenden
  • Geeigneten Adapter für das Bereitstellungsziel konfigurieren
  • Astro.props für die Datenweitergabe an Komponenten verwenden
  • astro:env Schema für typsichere Umgebungsvariablen verwenden
  • Astro.session für serverseitiges State-Management verwenden

DARF NICHT

  • Komponenten hydrieren, die keine Interaktivität benötigen (Verwenden Sie client: nur bei Bedarf)
  • client:only ohne Angabe des Frameworks verwenden
  • Bilder mit String-Pfaden importieren (Import-Anweisungen verwenden)
  • Schema-Validierung in Content Collections überspringen
  • server und hybrid Ausgabemodi falsch mischen
  • Auf Astro.request in vorgerenderten Seiten zugreifen
  • Browser-APIs im Frontmatter von Komponenten verwenden (serverseitiger Code)
  • Vergessen, Adapter für SSR-Bereitstellung zu installieren
  • Funktionen als Props an server:defer Komponenten übergeben (nicht serialisierbar)
  • Auf Astro.session in vorgerenderten Seiten zugreifen (erfordert On-Demand-Rendering)
  • src/content/config.ts für neue Projekte verwenden (verwenden Sie src/content.config.ts mit Loadern)

Kurzreferenz

Komponentenstruktur

---
// Komponenten-Skript (läuft auf dem Server)
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---

<!-- Komponenten-Template -->
<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* Standardmäßig gekapselt */
  h1 { color: navy; }
</style>

Direktiven-Priorität

  1. Keine Direktive → Statisches HTML, null JavaScript
  2. server:defer → Verzögertes serverseitiges Rendering (Server Island)
  3. client:load → Sofort beim Seitenladen hydrieren
  4. client:idle → Hydrieren, wenn der Browser im Leerlauf ist
  5. client:visible → Hydrieren, wenn die Komponente in den Viewport kommt
  6. client:media → Hydrieren, wenn die Media Query zutrifft
  7. client:only → SSR überspringen, nur auf dem Client rendern

Content Collection Schema (Astro 5+)

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

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

Server Island

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="Lädt..." />
</UserAvatar>

Ausgabeformat

Bei der Implementierung von Astro-Funktionen bereitstellen:

  1. Komponentendatei (.astro mit Frontmatter und Template)
  2. Konfigurationsaktualisierungen (astro.config.mjs falls erforderlich)
  3. Content Collection Schema (falls Collections verwendet werden)
  4. TypeScript-Typen (für Props und Daten)
  5. Kurze Erklärung der gewählten Hydrierungsstrategie

Technologien

Astro 5+/6+, Islands Architecture, Content Layer API (glob/file Loader, Live Loader), Zod Schemas, View Transitions API, Server Islands (server:defer), Sessions, Actions, Middleware, astro:env (typsichere Umgebungsvariablen), i18n Routing, Adapter (Node, Vercel, Netlify, Cloudflare, Deno), React/Vue/Svelte/Solid Integrationen, Bildoptimierung, MDX, Markdoc, TypeScript, Gekapseltes CSS, Tailwind CSS

Verwandte Skills