Astro-Entwicklung mit Claude Code: Content Collections, SSG und Build-Prüfung

Warum Claude Code gut zu Astro passt

Astro eignet sich besonders für Blogs, Dokumentationen, Portfolios, Produktseiten und andere Websites, bei denen Inhalte gelesen werden sollen. React-, Vue- oder Svelte-Komponenten sind möglich, aber Astro macht nicht automatisch aus jeder Seite eine große Client-App. Die Islands-Architektur bedeutet: Statischer Inhalt bleibt statisch, nur wirklich interaktive Teile wie Suche, Filter oder Buttons werden im Browser hydriert.

Claude Code hilft in Astro-Projekten vor allem dann, wenn es zuerst den Kontext liest. Eine Astro-Seite hängt nicht nur von einer Datei ab. astro.config.mjs, src/content.config.ts, src/pages/, src/components/, Bilder, Routing und Build-Befehle greifen ineinander. Wenn Claude Code vor dem Editieren einen Plan beschreibt, bleiben Änderungen kleiner und unnötige Abhängigkeiten fallen schneller auf.

Dieser Leitfaden nutzt die aktuelle Content-Collections-Struktur von Astro mit src/content.config.ts, astro/loaders und astro/zod. Prüfe die offiziellen Quellen, bevor du es in einem echten Projekt übernimmst: Claude Code Quickstart, Astro Content Collections, Astro template directives und Astro routing reference. Für Architekturfragen helfen außerdem der SSR/SSG-Vergleich und die SEO-Optimierung.

Den Umfang vor dem Editieren begrenzen

“Erstelle einen Astro-Blog” ist als Prompt zu breit. Claude Code kann dann Design, Routing, Inhaltsmodell und Dependencies gleichzeitig ändern. Besser ist ein enger Auftrag: statische Content-Site, MDX, Sitemap, typisiertes Frontmatter, Artikelliste, Tag-Seiten und Build-Verifikation.

npm create astro@latest my-astro-site
cd my-astro-site
npx astro add mdx sitemap tailwind
npm run dev

Danach sollte Claude Code erst lesen:

claude "Prüfe dieses Astro-Projekt als Content-Site. Lies astro.config.mjs, src/content.config.ts, src/pages und src/components. Erkläre vor jeder Änderung den Implementierungsplan und die Verifikationsbefehle."

Eine kleine Basiskonfiguration reicht:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  site: 'https://example.com',
  output: 'static',
  integrations: [mdx(), sitemap(), tailwind()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
    },
  },
});

Setze site vor der Veröffentlichung auf die echte Domain. Sitemap und Canonical URLs hängen davon ab; eine Beispiel-Domain schwächt spätere SEO-Prüfungen.

Content Collections mit der aktuellen API definieren

Content Collections machen aus Markdown- und MDX-Dateien typisierte Daten. Statt darauf zu hoffen, dass jedes Frontmatter stimmt, erzwingt ein Schema Titel, Beschreibung, Datum, Tags und optionale Felder. Gerade bei mehrsprachigen Seiten ist das wichtig, weil beim Übersetzen feste Felder leicht beschädigt werden.

// 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().max(80),
    description: z.string().max(120),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    heroImage: z.string().optional(),
  }),
});

export const collections = { blog };

Ein gezielter Review-Prompt ist hilfreicher als ein allgemeines “prüfe das”:

claude "Review src/content.config.ts für Astro 5. Prüfe aktuelle Content-Collections-API, description-Länge, draft-Filter, optionales updatedDate und mögliche alte API-Muster."

Damit wird das Schema zu einem Veröffentlichungsvertrag. Ein falsches Datum, eine zu lange Beschreibung oder ein kaputtes tags-Array fällt vor dem Deployment auf.

Praxisfall 1: Artikelliste mit Pagination

Der erste Praxisfall ist die Blogliste. Verlasse dich nicht auf die Reihenfolge von getCollection(). Filtere Entwürfe, sortiere nach Datum und übergib die Einträge an eine kleine Kartenkomponente.

---
// src/pages/blog/[...page].astro
import { getCollection } from 'astro:content';
import PostCard from '../../components/PostCard.astro';

export async function getStaticPaths({ paginate }) {
  const posts = (await getCollection('blog', ({ data }) => data.draft !== true))
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

  return paginate(posts, { pageSize: 12 });
}

const { page } = Astro.props;
---

<section class="mx-auto max-w-5xl px-4 py-10">
  <h1 class="text-3xl font-bold">Blog</h1>
  <div class="mt-8 grid gap-6 md:grid-cols-2">
    {page.data.map((post) => <PostCard post={post} />)}
  </div>
  <nav class="mt-10 flex justify-between">
    {page.url.prev ? <a href={page.url.prev}>Previous</a> : <span />}
    {page.url.next ? <a href={page.url.next}>Next</a> : <span />}
  </nav>
</section>

Die Karte zeigt nur die stabilen Metadaten:

---
// src/components/PostCard.astro
import type { CollectionEntry } from 'astro:content';

type Props = {
  post: CollectionEntry<'blog'>;
  lang?: string;
};

const { post, lang = 'de' } = Astro.props;
const href = lang === 'ja' ? `/blog/${post.id}/` : `/${lang}/blog/${post.id}/`;
const date = post.data.updatedDate ?? post.data.pubDate;
---

<article class="rounded border border-slate-200 p-5">
  <p class="text-sm text-slate-500">
    <time datetime={date.toISOString()}>{date.toLocaleDateString('de-DE')}</time>
  </p>
  <h2 class="mt-2 text-xl font-semibold">
    <a href={href}>{post.data.title}</a>
  </h2>
  <p class="mt-3 text-slate-700">{post.data.description}</p>
  <ul class="mt-4 flex flex-wrap gap-2">
    {post.data.tags.map((tag) => <li class="rounded bg-slate-100 px-2 py-1 text-xs">{tag}</li>)}
  </ul>
</article>

Dieses Muster passt für mindestens drei Szenarien: persönlicher Tech-Blog, interne Wissensbasis und Produkt-Changelog. In allen Fällen sollte Claude Code die Metadaten schützen, bevor es das Layout verändert.

Praxisfall 2: Tag-Seiten und gezielte Hydration

Der zweite Praxisfall ist ein Archiv pro Tag. Der typische Fehler: Das Tag-Label wird direkt als URL verwendet. Leerzeichen, Großbuchstaben und nicht-lateinische Zeichen können Routen fragil machen. Trenne URL-Slug und sichtbares Label.

---
// src/pages/tags/[tag]/[...page].astro
import { getCollection } from 'astro:content';
import PostCard from '../../../components/PostCard.astro';

const tagSlug = (tag) =>
  encodeURIComponent(tag.toLowerCase().trim().replace(/\s+/g, '-'));

export async function getStaticPaths({ paginate }) {
  const posts = await getCollection('blog', ({ data }) => data.draft !== true);
  const groups = new Map();

  for (const post of posts) {
    for (const label of post.data.tags) {
      const slug = tagSlug(label);
      const group = groups.get(slug) ?? { slug, label, posts: [] };
      group.posts.push(post);
      groups.set(slug, group);
    }
  }

  return [...groups.values()].flatMap((group) =>
    paginate(group.posts, {
      params: { tag: group.slug },
      props: { tag: group.label },
      pageSize: 10,
    }),
  );
}

const { page, tag } = Astro.props;
---

<section class="mx-auto max-w-5xl px-4 py-10">
  <h1 class="text-3xl font-bold">Tag: {tag}</h1>
  <div class="mt-8 grid gap-6 md:grid-cols-2">
    {page.data.map((post) => <PostCard post={post} />)}
  </div>
</section>

Der dritte Praxisfall ist Suche. Dafür muss nicht die ganze Seite clientseitig werden:

---
// src/pages/index.astro
import Hero from '../components/Hero.astro';
import SearchBox from '../components/SearchBox.tsx';
import LatestPosts from '../components/LatestPosts.astro';
---

<Hero />
<SearchBox client:visible />
<LatestPosts />

client:load ist für sofort interaktive Elemente. client:visible eignet sich für Komponenten, die erst beim Scrollen gebraucht werden. Claude Code sollte vor dem Hinzufügen einer Directive den Grund nennen.

Häufige Fehler und Prüfung

Fehler eins ist das Kopieren alter Content-Collections-Tutorials. Fehler zwei ist ein zu großer Auftrag wie “verbessere die ganze Seite”. Fehler drei ist das Vergessen von heroImage, description und Open Graph. Fehler vier ist die Annahme, dass ein erfolgreicher Build bereits vollständige Qualität bedeutet. Prüfe zusätzlich Pagination, interne Links, externe Links, mobile Darstellung und CTA.

npm run build
npx astro check
npm run preview

Bei Build-Fehlern zuerst klassifizieren lassen:

claude "Lies den Fehler von npm run build. Klassifiziere ihn als Astro-Syntax, Content-Collections-Schema, MDX-Code-Fence, Routengenerierung oder Linkproblem. Schlage dann den kleinsten Fix vor."

CTA und praktisches Ergebnis

Einsteiger starten sinnvoll mit dem kostenlosen Cheatsheet. Wer Vorlagen braucht, schaut in die Produkte. Für Teams, die Astro-Publishing, Review-Regeln und Claude-Code-Einführung strukturieren wollen, passt Training und Beratung.

Im Test war Claude Code schnell beim Erzeugen von .astro-Dateien und beim Verbinden der Seiten mit Collections. Manuell geprüft werden mussten aktuelle Astro-API, sichere Tag-URL-Codierung, möglicher Übergebrauch von client:load und der tatsächlich ausgeführte Build. Der stabile Ablauf war: Projekt lesen lassen, Änderung begrenzen, gegen offizielle Docs prüfen, Build ausführen und Preview ansehen.