Claude Code से Astro साइट बनाना: Content Collections, SSG और Build Checks

Claude Code और Astro साथ में क्यों उपयोगी हैं

Astro उन sites के लिए अच्छा framework है जहां मुख्य काम content पढ़ना है: blog, documentation, portfolio, product page या internal knowledge base. आप React, Vue या Svelte components भी इस्तेमाल कर सकते हैं, लेकिन Astro हर page को heavy client-side app नहीं बनाता. Island architecture का मतलब है कि static content static रहता है और सिर्फ search, filter, button जैसे interactive हिस्से browser में JavaScript load करते हैं.

Claude Code का असली फायदा तब मिलता है जब आप उससे पहले project पढ़वाते हैं. Astro में सिर्फ एक page file नहीं होती; astro.config.mjs, src/content.config.ts, src/pages/, src/components/, images, routes और build commands सभी जुड़े होते हैं. अगर Claude Code edit करने से पहले plan बताए, तो unnecessary dependencies और बड़े rewrite से बचा जा सकता है.

यह guide Astro 5 के current Content Collections pattern पर आधारित है: src/content.config.ts, astro/loaders और astro/zod. काम शुरू करने से पहले official docs देखें: Claude Code Quickstart, Astro Content Collections, Astro template directives और Astro routing reference. Architecture समझने के लिए SSR/SSG comparison और SEO guide भी उपयोगी हैं.

Scope पहले साफ करें

“Astro blog बना दो” जैसा prompt बहुत broad है. Claude Code design, routing, content model और dependency एक साथ बदल सकता है. बेहतर है कि आप साफ लिखें: static content site, MDX, sitemap, typed frontmatter, post list, tag pages और build verification.

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

Project बनने के बाद पहले review कराएं:

claude "इस Astro project को content site की तरह review करो. astro.config.mjs, src/content.config.ts, src/pages और src/components पढ़ो. Edit करने से पहले implementation plan और verification commands बताओ."

Basic config छोटा रखें:

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

Publish करने से पहले site को real domain से बदलें. Sitemap और canonical URL इसी value पर निर्भर करते हैं.

Content Collections current API से define करें

Content Collections Markdown और MDX files को typed data की तरह manage करते हैं. Frontmatter में title, description, pubDate, tags जैसे fields को schema से validate किया जाता है. Multilingual site में यह खास जरूरी है, क्योंकि translation करते समय fixed frontmatter गलती से बदल सकता है.

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

Claude Code से focused review मांगें:

claude "src/content.config.ts को Astro 5 के लिए review करो. Current Content Collections API, description length, draft filter, optional updatedDate और old API usage check करो."

इस schema से publishing contract बनता है. Date गलत हो, description बहुत लंबी हो या tags array न हो, तो deployment से पहले error मिल जाता है.

Example 1: Post list और pagination

पहला real use case blog index है. getCollection() की default order पर भरोसा न करें. Draft हटाएं, date के हिसाब से sort करें और entries को card component में दें.

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

Card component में metadata stable रखें:

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

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

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

यह pattern personal tech blog, internal knowledge base और product changelog तीनों में काम आता है. Styling बदलने से पहले Claude Code को title, date, description और tags preserve करने को कहें.

Example 2: Tag pages और selective hydration

दूसरा use case tag archive है. Tag label को directly URL में डालना गलती है, क्योंकि spaces, uppercase और Hindi जैसे characters route को fragile बना सकते हैं. URL slug और display 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>

तीसरा use case search box है. पूरे page को client app बनाने की जरूरत नहीं:

---
// 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 तभी लगाएं जब component तुरंत interactive होना जरूरी हो. client:visible तब बेहतर है जब component viewport में आने के बाद load हो सकता है.

Common mistakes और verification

पहली गलती है पुराने Content Collections tutorial को copy करना. दूसरी गलती है Claude Code से पूरा site एक साथ बदलवाना. तीसरी गलती है heroImage, description और Open Graph को भूल जाना. चौथी गलती है build pass होते ही publish कर देना. Pagination, internal links, external links, mobile layout और CTA भी check करें.

npm run build
npx astro check
npm run preview

Build fail हो तो पहले classify कराएं:

claude "npm run build failure पढ़ो. इसे Astro syntax, Content Collections schema, MDX code fence, route generation या link issue में classify करो. फिर smallest fix बताओ."

CTA और 실제 result

शुरुआत करने वालों के लिए free cheat sheet सही entry point है. Templates चाहिए तो products देखें. Team में Astro publishing, review rules और Claude Code workflow बनाना हो तो training and consultation बेहतर अगला कदम है.

Practical test में Claude Code .astro files जल्दी बना देता है, लेकिन current Astro API, tag URL encoding, बहुत ज्यादा client:load, और actual build execution को manually देखना पड़ा. सबसे stable workflow था: project पढ़वाना, scope छोटा रखना, official docs से मिलाना, build चलाना और preview check करना.