DEV Community: Ted

Building an Astro Blog with Claude Code

Ted — Tue, 19 May 2026 15:42:09 +0000

In part 1 I explained why I moved from Lovable.dev to Astro for SEO. Lovable builds React apps that serve empty HTML to Googlebot — Astro builds static HTML that Google can read instantly, no JavaScript required.

This post is part 2: actually building the blog. But instead of walking you through every command manually, I handed it to Claude.

The Prompt

One prompt. That's it.

Build me an SEO-ready Astro blog from scratch with Tailwind, MDX, RSS feed, sitemap, and fonts

From that, Claude installed everything, built the full project structure, and had a working blog ready to deploy. Here's exactly what happened — including the decisions it made that I didn't ask for, and where it hit problems.

What Claude Installed

Claude ran the following commands in sequence:

npm create astro@latest astro-demo

When prompted:

Template: Empty
TypeScript: Yes, strict
Install dependencies: Yes
Initialize git repo: Yes

Then added the integrations:

npx astro add tailwind
npx astro add mdx

Then fonts and RSS:

npm install @fontsource-variable/inter @fontsource/jetbrains-mono
npm install @astrojs/rss

One thing it caught that I didn't ask about: it skipped @astrojs/sitemap entirely. That integration crashes on Astro 4.16+ with a Cannot read properties of undefined (reading 'reduce') error. Claude knew this and built a manual sitemap endpoint at src/pages/sitemap.xml.ts instead. That's the kind of thing you only know if you've hit the bug — or in this case, if your agent has enough context to anticipate it.

What Claude Built

The full project structure:

src/
├── components/
│   ├── Header.astro
│   ├── PostList.astro
│   └── SeriesNav.astro
├── content/
│   └── posts/        # .md/.mdx files go here
├── layouts/
│   └── BaseLayout.astro
├── pages/
│   ├── index.astro
│   ├── about.astro
│   ├── archive.astro
│   ├── posts/[slug].astro
│   ├── tags/[tag].astro
│   ├── categories/[category].astro
│   ├── series/[series].astro
│   ├── rss.xml.ts
│   └── sitemap.xml.ts
└── styles/
    └── globals.css

The scope here is worth noting. I asked for a blog. Claude built a full content taxonomy — tags, categories, series navigation, archive page, RSS feed, sitemap. Every route it created serves a purpose for either discoverability or SEO. Tag and category pages in particular matter for topic clustering: they give Google a signal that this site covers a coherent subject area, not just a loose collection of posts, which helps individual posts inherit topical authority over time.

The SEO Decisions Baked Into BaseLayout

This is the part most tutorials skip. The layout file is where most of your SEO either works or doesn't.

Claude built BaseLayout.astro with the following automatically wired up for every page:

Canonical URL — generated from the site URL and current path. Every page declares its own canonical, which prevents duplicate content issues if Vercel's preview URLs ever get indexed.

Open Graph tags — og:title, og:description, og:image, og:url, og:type. These control how the page appears when shared on Twitter, LinkedIn, or Slack. Claude wired them to the same frontmatter fields as the page meta, so there's no separate OG configuration needed per post.

Twitter Card — summary_large_image by default, so post shares show a full image preview rather than a small thumbnail.

JSON-LD structured data — three schemas per post page: Article, WebSite, and BreadcrumbList. These are what Google uses to understand the page type, authorship, and navigation hierarchy. On a CSR site this has to load via JavaScript and might not be seen by crawlers. On Astro it's in the HTML before any JavaScript runs.

All of this is automatic. Drop a new post file in src/content/posts/, push, and every one of those meta tags is generated correctly with no manual input.

The Content Schema

Claude defined the content schema in src/content/config.ts:

title: string
description: string
publishDate: string
updatedDate?: string
tags: string[]
category: 'guides' | 'notes' | 'builds'
draft: boolean
image?: string
imageAlt?: string
series?: string
part?: number

The series and part fields were something I asked for specifically — I knew I'd want to group related posts. Claude built SeriesNav.astro to handle the series UI automatically: previous/next links within a series, plus a link back to the series index page. Posts without series in their frontmatter render as standalone, no extra configuration needed.

Where It Hit Problems

It wasn't perfect. Two things needed manual fixes.

The Vercel deploy config. The first deploy failed because Vercel defaulted to the wrong output directory. Claude had to add a vercel.json file to the root:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "astro"
}

After that it deployed cleanly.

The GitHub push from the server. Claude Code runs on my homeserver, not my local machine. To push to GitHub from the server, the git remote needs a personal access token embedded in the URL — standard HTTPS auth doesn't work in a headless environment. Claude flagged this and set the remote correctly:

git remote set-url origin https://TOKEN@github.com/username/repo

One security note: treat this token like a password. Don't commit it, don't leave it in shell history. Either use a fine-grained GitHub token scoped to the single repo, or switch to SSH keys if you're on a machine you control long-term.

Not a Claude Code limitation — just a server environment reality. Worth knowing if you're running agents on a remote machine.

Push to GitHub and Deploy

Once the remote was configured:

git add .
git commit -m "Initial blog build"
git push origin master

Then on Vercel: Add New Project → import the repo → Deploy. Vercel detects Astro automatically but needs one config file to correctly set the output directory — that's the vercel.json above. Once it's there, no further build configuration is needed.

Within two minutes the blog was live at a Vercel URL.

The Result

A fully working, SEO-ready Astro blog — deployed on Vercel, with tags, categories, series navigation, RSS, sitemap, JSON-LD schema, Open Graph, and canonical URLs — built from a single prompt in one session. The full build ran in just over 7 minutes.

(Demo video coming soon.)

Live demo: astro-demo-theta-tawny.vercel.app

What This Actually Demonstrates

The point isn't that Claude wrote the code. It's that agentic workflows collapse the gap between a decision and a working system.

The traditional path for this project: read the Astro docs, pick a template, configure Tailwind, wire up MDX, figure out why @astrojs/sitemap crashes, build the content schema, write the base layout, set up JSON-LD manually, troubleshoot the Vercel config, push. Half a day minimum, probably longer.

The agentic path: one prompt, review the output, fix two issues, ship.

The output is the same. The time investment is not.

That's what this blog documents — not AI as a novelty, but AI as operational infrastructure. The blog itself was built the same way the systems it writes about are built: give the agent a clear goal, stay in the loop on decisions that matter, and let it handle the implementation.

Why the SEO Foundation Matters More Than the Framework

A lot of people building blogs with AI tools focus on the wrong thing. They want the blog to look good, deploy fast, and be easy to write in. Those matter. But the SEO foundation — the stuff that determines whether Google can read and understand your content — is decided before you write a single post.

Here's what this build gets right by default:

Every page is crawlable on the first request. No JavaScript rendering required. Googlebot hits the URL, gets complete HTML, indexes it. That's it.

Structured data is present and correct on every post. The JSON-LD schema Claude wired into BaseLayout.astro tells Google this is an Article, who authored it, when it was published, and where it sits in the site hierarchy. This is what enables rich results in SERPs — date stamps, breadcrumbs, author attribution. On a manually-built blog these are easy to get wrong or forget entirely. Here they're generated automatically from frontmatter.

The sitemap updates on every deploy. The custom sitemap.xml.ts endpoint queries the content collection and generates a fresh sitemap at build time. Every new post is automatically included with its correct URL and publish date. You never manually update a sitemap or worry about a new post being missed.

RSS keeps returning readers engaged. The RSS feed at /rss.xml is a low-effort retention mechanism. Readers who subscribe get notified of new posts without you needing to send an email or post on social. For a technical blog, a meaningful chunk of the audience prefers RSS — it's worth having from day one.

None of this required separate configuration. It was all handled in the initial build.

Write Your First Post

Drop a .md file in src/content/posts/:

---
title: "My First Post"
description: "A short description for Google."
publishDate: "2026-04-27"
tags: ["astro", "seo"]
category: "guides"
draft: false
---

Your content here.

Push to GitHub. Vercel redeploys automatically. Done.

The build is the easy part. The harder question is what you do next — how you monitor whether Google is actually finding and indexing your posts, and what to do when something goes wrong. That's what the rest of this series covers. Browse all posts in the Astro SEO Blog series.

Astro vs Lovable for SEO: Why Static Sites Win

Ted — Tue, 19 May 2026 15:18:29 +0000

My monitoring script fired at 3am. A content site I manage — the top-ranking page on that domain, the one its entire internal linking structure pointed to — had dropped out of the Google index entirely.

Not penalized. Not a manual action. Just gone — as if it never existed.

The diagnosis was quick. The site ran on a CSR stack — React, client-side rendered. Googlebot had visited, got a near-empty HTML shell, and moved on before JavaScript had a chance to build the DOM. At some point Google stopped waiting and dropped the page entirely.

The fix took less than an hour. Within a day or two it was back — and when it reappeared, it had moved from position 3 to position 2. Fixing the rendering issue properly actually moved it up.

That's the thing about CSR: it doesn't just risk a penalty. It quietly suppresses pages that should be ranking, and you won't know until they disappear.

The fix was a custom prerender layer — a static HTML snippet injected directly into the React root div under the id ssr-prerender. Googlebot sees real content immediately. Real users get the React app as normal, which replaces it on load. It works. But it's a patch, not a solution — something you bolt on after the fact, maintain separately, and have to remember every time you add a new page or change content.

Client-side rendering means the server returns an empty HTML shell. The browser runs JavaScript to build the page. That works for users. It's unreliable for crawlers — and the cost doesn't show up immediately. It shows up weeks later when pages quietly stop ranking.

Lovable is built for apps, not blogs. But plenty of people use it for content sites anyway — that's the mistake this post is about.

When I decided to build this blog — a place to document agentic AI workflows that I actually want people to find — I wasn't going to patch my way through it again.

The Tools I Looked At

Before landing on a stack, I mapped out the real options. Not just "what's popular" but what the actual tradeoffs are for a content site in 2026.

Lovable

Lovable is a prompt-to-app builder. You describe what you want, it generates a React codebase, you deploy. The UX is genuinely impressive for web apps — forms, dashboards, interactive tools.

Update (May 2026): Lovable shipped SSR as a first-class feature. New apps are now server-side rendered — Googlebot gets real HTML on the first request, the crawlability problem is gone for new projects. Existing apps get automatic pre-rendering at build time, which fixes the indexability issue without a DIY script.

The performance gap with SSG still exists. New Lovable apps ship a full React bundle and add server latency to every request — a static site serves pre-built HTML from a CDN edge node with no per-request compute. For a pure content blog where every page is the same for every visitor and LCP matters, SSG is still the faster path. But the hard wall that made Lovable the wrong choice for organic search is no longer there for new projects.

I still use it for clients who need web apps or interactive content. For a pure content site with no dynamic requirements, the SSG argument below still holds.

Cursor

Cursor is a VSCode fork with an embedded AI assistant — excellent for developers who want faster coding without giving up control. It doesn't pick a framework or manage deployments, so the SEO tradeoffs are entirely yours to manage.

What I Actually Use

My setup is deliberately boring:

ThinkCentre PC, bare metal Ubuntu, no cloud VM
Claude Code over SSH as the agent
Astro 4 — SSG, zero client JS by default
Vercel for deploy, auto-deploys on every push to master

Claude Code handles file editing, refactoring, and multi-step builds. I review diffs, approve writes, and push. The agent runs in my terminal — no subscription to a hosted IDE, no vendor controlling my environment.

Astro was the obvious framework choice once I ruled out React-based options. Every page is static HTML at build time. No JavaScript ships to the browser unless you explicitly add it. Googlebot sees exactly what a user sees, because there's no rendering step to skip.

The content schema is straightforward MDX files in src/content/posts/. Writing a new post is dropping a Markdown file and pushing. No CMS, no API calls, no paid tier. The overhead is real but front-loaded — you configure image optimization, redirects, and the content schema once. After that it doesn't move. That's a different kind of maintenance than patching a prerender layer every time you add a page.

Astro vs Lovable for SEO: The Real Comparison

This is the question that matters if you're using AI-assisted tools to build content sites.

Lovable is built for speed — you describe a UI, it ships React. That's genuinely useful for products, dashboards, anything interactive. But for a content site where organic search is the point, React's default rendering model is the wrong starting point.

Googlebot has a two-wave crawl model. First wave: fetch the raw HTML. Second wave: render JavaScript. The second wave happens on a delay — sometimes hours, sometimes days — and isn't guaranteed for every page on every crawl. For a new site or a page with low crawl budget, Google may only ever see the first wave. On a CSR site, that first wave is an empty shell.

Astro doesn't have this problem. The HTML is complete at build time — every page is just a file on disk, served directly. Googlebot gets the same document a user gets, on the first request, every time. An Astro page can be indexed the same day it's published. A Lovable page might take two weeks and a manual fetch request in Search Console to force the second render wave.

For a blog where every post is a potential traffic source, that's not a minor difference.

The SEO Tradeoff That Actually Matters

Here's the thing nobody says clearly: your platform choice is an SEO decision.

Every framework has a default rendering strategy. If that default is client-side, you're opting into a crawl risk. You can mitigate it, but you can't fully eliminate it — and every mitigation adds operational overhead.

To be precise: the risk is probabilistic, not guaranteed. High-authority domains with strong crawl frequency and deep internal linking can rank fine on CSR — Google's renderer has improved significantly, and a well-established site gives Googlebot reason to come back for the second wave. The risk is highest where the stakes are also highest: new sites, low crawl budget pages, and content that needs to index fast to catch a trend or a seasonal window. That's exactly where most content blogs live.

Static site generators like Astro, Eleventy, and Hugo don't have this problem. The HTML is there at request time, before any crawler or user arrives. There's nothing to render, nothing to wait for, nothing to patch around.

Beyond crawlability, static sites have compounding SEO advantages:

Speed. Astro ships zero JavaScript by default — the browser gets a finished HTML file and paints immediately. On a React CSR site, the browser downloads a JS bundle, parses it, executes it, then renders. That sequence adds hundreds of milliseconds to LCP on a cold load, and LCP is a Core Web Vitals signal Google uses as a ranking factor. My Astro blog consistently scores 95+ on PageSpeed Insights mobile. My client sites on CSR stacks rarely break 70 without active optimization.

Structured data. In Astro, JSON-LD schema lives in the base layout — defined once, present on every page at build time, no runtime dependency. On a CSR site, your structured data is injected by JavaScript. If the script errors, is blocked, or executes after Googlebot's render window closes, your schema is invisible. You won't see this failure in GSC until it's already cost you rich results.

Here's what that looks like in practice — the relevant slice of an Astro base layout:

---
const { title, description, canonicalURL } = Astro.props;
const schema = {
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": title,
  "description": description,
  "url": canonicalURL,
};
---
<head>
  <link rel="canonical" href={canonicalURL} />
  <script type="application/ld+json" set:html={JSON.stringify(schema)} />
</head>

The canonical and structured data are rendered into the HTML at build time — no hydration, no runtime dependency, no silent failure.

Canonical URLs. Static generation makes canonicals deterministic. Every page has one URL, set at build time, baked into the HTML. CSR frameworks with dynamic routing can silently generate duplicate URLs under different query parameters — /posts/my-article and /posts/my-article?ref=homepage both return 200s, both get crawled, and both dilute the canonical signal unless you've explicitly handled it. With Astro, this class of problem doesn't exist.

For a content blog that needs to rank, none of this is optional. It's the baseline.

The Middle Path

Astro isn't the only way out of CSR. It's worth naming the alternatives so this doesn't read as "Astro or nothing."

Next.js gives you two paths to HTML-first rendering. output: 'export' is a full static export — no server features, no API routes, no ISR, just HTML files on disk with the same crawlability as Astro. getStaticProps is SSG inside a hybrid Next.js app that still has server routes, API endpoints, and ISR — more flexible, but you're choosing the rendering strategy per page deliberately rather than accepting a default. If you're already comfortable in Next.js, either path works. Astro islands (partial hydration) let you drop interactive React or Svelte components into otherwise static pages without shipping a full JS bundle. For a content site that needs one or two dynamic widgets, that's a clean solution.

The principle is the same regardless of which tool you pick: HTML-first by default, JavaScript added deliberately. Astro makes that the default. Next.js makes it possible but requires you to choose it. Lovable doesn't give you the option.

What I'd Tell Someone Starting Now

If you're building a web app — a tool, a dashboard, something with real interactivity — Lovable is a legitimate choice. Ship fast, iterate, worry about SEO when the product is solid.

If you're building a content site — a blog, a documentation site, a resource hub where organic traffic is the point — don't use a CSR framework as your foundation. The crawl risk is real, the fixes are patches, and you'll spend time maintaining workarounds that a static site simply doesn't need.

One honest limit worth naming: pure SSG pre-builds every page identically at deploy time. That works perfectly for content. It gets awkward when every page needs to render differently per user — a fully personalised feed, for example. For that you switch Astro to output: 'hybrid' or output: 'server' mode, which enables server-side rendering on specific routes while keeping everything else static. Auth and Supabase integration work fine in Astro either way — login flows, protected routes via middleware, user dashboards as islands. The constraint isn't "you can't do auth," it's "fully personalised page-level content at scale wants SSR, not SSG."

Astro is free, deploys to Vercel in one click, and handles all the SEO fundamentals out of the box. The learning curve is light if you know HTML and basic JavaScript. It's not the only answer — but for a new content site where every page needs to index fast, it's the lowest-friction path to getting that right.

Read part 2 to see how I built this blog in a single Claude Code session.

Part 3 covers the Lovable SSR update in detail — what pre-rendering for existing apps actually fixes, what it doesn't, and when the Astro argument still holds: Lovable Shipped SSR. Here's What That Actually Changes.