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

Every time you spin up a new content site, the framework question burns hours you could spend actually building. Next.js pulls you toward a full React app even when you just need static pages. Gatsby’s plugin maze eats an afternoon before you’ve written a line of content. And plain static-site generators feel like stepping backward a decade. We hit that wall when rebuilding our showcase site, narrowed the field to Astro, Next.js (static export), and MkDocs Material, and Astro won out convincingly.

Why Astro?

1. Zero JavaScript by Default

Astro sends zero JavaScript to the browser unless you tell it otherwise. The payoff is immediate:

  • Fast page loads with no wasted bytes
  • Near-perfect Lighthouse scores without extra tuning
  • Lower bandwidth consumption for every visitor
  • Stronger SEO signals from raw speed

The reality is that most static sites have no need for client-side JavaScript on the vast majority of their pages. Astro was designed around that insight.

2. Content Collections

Content collections are one of Astro’s standout features for sites with a lot of Markdown:

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([]),
  }),
});

What makes them so useful:

  • 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 actually need interactivity, the islands architecture handles it cleanly:

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

Only the interactive pieces ship JavaScript. Everything else stays as plain HTML. This works especially well for:

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

If you’ve ever shipped a mostly-static site on a framework that bundles 200KB of JavaScript just to render text on a screen, you already know why this matters.

4. Framework Agnostic

Not sold on vanilla JS? Bring React, Vue, Svelte, or Solid along:

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

Different framework components can live on the same page without conflict. Use whatever fits the job.

Real-World Performance

Our production numbers speak for themselves:

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

We didn’t spend time hand-tuning any of this. Astro’s defaults just produce fast sites.

Developer Experience

Hot Module Reload

Edits show up instantly in the browser. No full page refreshes, no lost component state.

TypeScript First

Types are built in from the start. Errors surface in your editor, not in production.

Markdown + Components

Author in Markdown and pull in components wherever you need them:

# My Post

Here's a custom component:

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

Back to regular markdown...

Build Performance

The full site compiles in under 10 seconds, covering:

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

Cloudflare Pages Integration

Astro pairs naturally with Cloudflare Pages:

  • Push to Git, deploy automatically
  • Preview URLs generated for every PR
  • Edge-cached static assets worldwide
  • Custom headers and redirects supported
  • No configuration required to get started

What We’d Change

Honestly, not much. A few small friction points:

  • The hydration directives for islands take some getting used to
  • Parts of the plugin ecosystem are still catching up
  • Documentation has gaps in a few areas

None of these have been serious blockers.

Should You Use Astro?

Probably yes, if:

  • Your site is content-driven (blog, docs, marketing pages)
  • Performance and SEO matter to you
  • You want a modern workflow (TypeScript, hot reload, component authoring)
  • Static generation fits your use case

Probably not, if:

  • You need real-time data on every request
  • The entire site is dynamic (dashboards, authenticated apps)
  • You depend on server-side rendering with sessions and auth

Astro turned out to be exactly what we needed: fast output, modern tooling, and a workflow that stays out of the way.

Over to You

Have you tried Astro for your own projects? We’d genuinely like to hear what framework trade-offs you’ve run into — whether it’s migration headaches, performance surprises, or ecosystem gaps that pushed you toward a different tool. Drop us a line on our contact page or check out our source code to see exactly how we put this site together.

Resources: