Mission Log

Why We Chose Astro for Our Showcase Site

Exploring Astro's islands architecture, content collections, and why it's perfect for static sites with dynamic needs.

Web

The Framework Decision

When rebuilding our showcase site, we evaluated three options: Astro, Next.js (static), and MkDocs Material. Each had strengths, but Astro emerged as the clear winner.

Why Astro?

1. Zero JavaScript by Default

Astro ships zero JavaScript to the browser unless you explicitly opt in. This means:

  • Blazing fast page loads
  • Perfect Lighthouse scores out-of-the-box
  • Lower bandwidth for users
  • Better SEO rankings

Most static sites don’t need client-side JavaScript for 90% of their content. Astro embraces this philosophy.

2. Content Collections

Astro’s content collections are a game-changer for content-heavy sites:

const postsCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    summary: z.string().max(160),
    date: z.date(),
    tags: z.array(z.string()).default([]),
  }),
});

Benefits:

  • Type safety - Zod schemas validate frontmatter at build time
  • Auto-completion - Full TypeScript support in your editor
  • Query API - getCollection() makes it easy to fetch and filter content
  • MDX support - Embed components directly in markdown

3. Islands Architecture

When you do need interactivity, Astro’s islands architecture is brilliant:

<Search client:load />
<DarkModeToggle client:idle />

Only the interactive parts ship JavaScript. The rest is pure HTML. This is perfect for:

  • Search components
  • Theme toggles
  • Interactive demos
  • Comment systems

4. Framework Agnostic

Don’t like our choice of vanilla JS? Use React, Vue, Svelte, or Solid:

<ReactComponent client:load />
<VueWidget client:visible />

All components can coexist on the same page. Mix and match as needed.

Real-World Performance

Our site achieves:

  • 100/100 Lighthouse performance score
  • < 1s Time to Interactive
  • < 50KB initial JavaScript payload
  • A+ grade on web.dev

This is without any optimization effort. Astro just defaults to fast.

Developer Experience

Hot Module Reload

Changes appear instantly. No full page refreshes, no lost state.

TypeScript First

Everything is typed by default. Catch errors before they hit production.

Markdown + Components

Write in Markdown, drop in components when needed:

# My Post

Here's a custom component:

<CodeBlock lang="javascript" code={myCode} />

Back to regular markdown...

Build Performance

Our site builds in < 10 seconds with:

  • 50+ pages
  • 100+ markdown files
  • Image optimization
  • Sitemap generation
  • RSS feed

Cloudflare Pages Integration

Astro + Cloudflare Pages is a perfect match:

  • Push to Git → Auto-deploy
  • Preview URLs for every PR
  • Edge-cached static files
  • Custom headers and redirects
  • Zero config needed

What We’d Change

Nothing major. Minor quibbles:

  • Learning curve for islands hydration directives
  • Some plugins still maturing
  • Documentation could be more comprehensive

But these are tiny compared to the benefits.

Should You Use Astro?

Yes, if:

  • You’re building a content-heavy site (blog, docs, marketing)
  • You value performance and SEO
  • You want modern DX (TypeScript, hot reload, etc.)
  • You’re okay with static site generation

No, if:

  • You need real-time data on every request
  • Your site is 100% dynamic (dashboards, apps)
  • You need server-side rendering with auth/sessions

For us, Astro was the obvious choice. Fast, modern, and a joy to work with.

Learn More