Membangun Situs Astro dengan Claude Code: Collections, SSG, dan Validasi

Mengapa Claude Code cocok untuk Astro

Astro cocok untuk blog, dokumentasi, portfolio, halaman produk, dan situs yang sebagian besar kontennya dibaca. Kamu tetap bisa memakai komponen React, Vue, atau Svelte, tetapi Astro tidak memaksa semua halaman menjadi aplikasi client-side yang berat. Island architecture berarti bagian statis tetap statis, sedangkan komponen seperti search, filter, atau tombol interaktif saja yang di-hydrate di browser.

Claude Code paling berguna ketika diminta memahami project sebelum mengedit. Dalam Astro, hasil akhir tidak hanya ditentukan oleh satu file halaman. astro.config.mjs, src/content.config.ts, src/pages/, src/components/, gambar, route, dan perintah build semuanya saling terkait. Jika Claude Code membaca dulu dan menjelaskan rencana, perubahan biasanya lebih kecil dan dependency yang tidak perlu bisa dihindari.

Panduan ini memakai pola Content Collections Astro yang sekarang: src/content.config.ts, astro/loaders, dan astro/zod. Sebelum menerapkannya di project nyata, cek sumber resmi: Claude Code Quickstart, Astro Content Collections, Astro template directives, dan Astro routing reference. Untuk pilihan arsitektur, baca juga perbandingan SSR/SSG dan optimasi SEO.

Mulai dengan scope yang jelas

Prompt seperti “buatkan blog Astro” terlalu luas. Claude Code bisa mengubah desain, route, model konten, dan dependency sekaligus. Lebih aman jika scope ditulis jelas: situs konten statis, MDX, sitemap, frontmatter bertipe, daftar artikel, halaman tag, dan verifikasi build.

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

Setelah project dibuat, minta Claude Code membaca dulu:

claude "Review project Astro ini sebagai situs konten. Baca astro.config.mjs, src/content.config.ts, src/pages, dan src/components. Sebelum mengedit, jelaskan rencana implementasi dan perintah verifikasi."

Konfigurasi awal bisa tetap sederhana:

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

Ganti site dengan domain produksi sebelum publish. Sitemap, canonical URL, dan beberapa pemeriksaan SEO bergantung pada nilai ini.

Definisikan Content Collections dengan API saat ini

Content Collections membuat file Markdown dan MDX diperlakukan sebagai data yang punya struktur. Bukan sekadar berharap semua artikel memiliki frontmatter yang benar, kamu mendefinisikan schema agar Astro bisa menangkap error saat development. Ini penting untuk situs multilingual karena proses terjemahan bisa merusak frontmatter tanpa sengaja.

// 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 };

Prompt review yang spesifik lebih membantu:

claude "Review src/content.config.ts untuk Astro 5. Cek API Content Collections saat ini, panjang description, filter draft, updatedDate opsional, dan kemungkinan API lama."

Schema ini menjadi kontrak publish. Tanggal salah, description terlalu panjang, atau tags bukan array bisa ditemukan sebelum deploy.

Use case 1: daftar artikel dengan pagination

Use case pertama adalah halaman daftar artikel. Jangan mengandalkan urutan dari getCollection(). Filter draft, urutkan berdasarkan tanggal, lalu kirim entry ke komponen card.

---
// 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>

Komponen card cukup menampilkan metadata utama:

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

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

const { post, lang = 'id' } = 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('id-ID')}</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>

Pola ini cocok untuk tiga contoh nyata: blog teknis pribadi, knowledge base internal, dan changelog produk. Di semua kasus, metadata harus stabil sebelum styling diubah.

Use case 2: halaman tag dan hydration selektif

Use case kedua adalah arsip per tag. Kesalahan umum adalah memakai label tag langsung sebagai URL. Spasi, huruf besar, dan karakter non-Latin bisa membuat route rapuh. Pisahkan slug URL dan label tampilan.

---
// 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>

Use case ketiga adalah search box. Jangan ubah seluruh halaman menjadi aplikasi client hanya untuk satu komponen:

---
// 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 dipakai untuk UI yang harus interaktif segera. client:visible lebih cocok jika komponen boleh menunggu sampai masuk viewport.

Kesalahan umum dan verifikasi

Kesalahan pertama adalah menyalin tutorial Content Collections lama. Kesalahan kedua adalah meminta Claude Code memperbaiki seluruh situs sekaligus. Kesalahan ketiga adalah melupakan heroImage, description, dan Open Graph. Kesalahan keempat adalah menganggap build berhasil berarti sudah siap publish. Tetap cek pagination, internal link, external link, tampilan mobile, dan CTA.

npm run build
npx astro check
npm run preview

Jika build gagal, minta klasifikasi dulu:

claude "Baca kegagalan npm run build. Klasifikasikan sebagai syntax Astro, schema Content Collections, MDX code fence, route generation, atau masalah link. Lalu usulkan perbaikan terkecil."

CTA dan hasil yang dicoba

Untuk mulai, gunakan cheat sheet gratis agar perintah dasar Claude Code lebih mudah diingat. Jika butuh template, lihat produk. Untuk tim yang ingin merapikan workflow Astro, aturan review, dan adopsi Claude Code, lanjutkan ke training dan konsultasi.

Saat dicoba, Claude Code cepat membuat file .astro dan menghubungkan halaman dengan collections. Namun API Astro terbaru, encoding URL tag, penggunaan client:load yang berlebihan, dan eksekusi build tetap perlu dicek manual. Alur paling stabil adalah membaca project, membatasi perubahan, membandingkan dengan dokumentasi resmi, menjalankan build, lalu memeriksa preview.