AI AI Tools Guidebook
Indie Dev & Website Building

When Astro Is the Right Choice (And When It Isn't)

A practical 2026 guide to when Astro is the best framework for your site and when you should reach for Next.js, Hugo, or plain HTML instead.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Astro is a great default for content-heavy sites, but it is not a universal answer. Here is when it shines, when it struggles, and how to decide.

Background

Astro became popular because it ships almost no JavaScript by default, which makes content sites fast and easy to host. But the same architecture that makes Astro great for blogs makes it awkward for highly interactive applications. By 2026, Astro is mature enough that the choice is no longer “is it ready” — it is “is it the right shape for my project”.

How to tell

  • Your site is mostly static content — blog, documentation, marketing pages, a small store.
  • You want excellent Core Web Vitals with minimal effort.
  • You don’t need to ship complex client-side state across many routes.
  • You are comfortable writing pages in .astro or .mdx files.
  • Your team is small and doesn’t need an opinionated app framework.

Quick verdict

Pick Astro when content is the product. Pick Next.js when interactivity is the product. Pick plain HTML when even Astro is overkill.

Step by step

  1. List the page types your site needs: marketing, blog, docs, dashboard, checkout. For each, mark “static” or “interactive”. If more than 70% are static, Astro is a strong default.

  2. Spin up the starter and benchmark it before committing:

npm create astro@latest -- --template starlight my-spike
cd my-spike
npm install
npm run dev      # localhost:4321
  1. Add a content collection — this is Astro’s strongest feature and the thing you should actually try before deciding:
// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const articles = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    publishedAt: z.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { articles };

Drop a sample .mdx file in src/content/articles/hello.mdx and render it with getCollection('articles'). If this workflow feels natural, you have your answer.

  1. If you need React/Vue/Svelte islands, add only the one you actually need — don’t mix three:
npx astro add react       # or vue, svelte, solid, preact
---
// src/pages/index.astro
import Counter from '../components/Counter.tsx';
---
<html>
  <body>
    <h1>Static heading</h1>
    <Counter client:load />   <!-- only this island hydrates -->
  </body>
</html>
  1. Build and inspect the output. The JS payload for a content-only page should be near zero:
npm run build
ls -lh dist/_astro/*.js 2>/dev/null | head
# a content page with no islands ships ~0 KB of JS
  1. Confirm your hosting target. Static output works on every host; hybrid/SSR needs an adapter:
// astro.config.mjs — hybrid example
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',
  adapter: vercel(),
});
  1. Commit to Astro only after this 1-day spike — framework swaps mid-build are expensive.

Common pitfalls

  • Choosing Astro for an app-style project then hitting friction every time you add interactivity.
  • Mixing too many UI framework integrations (React + Vue + Svelte) — bundle size and complexity creep in.
  • Skipping content collections and storing data ad-hoc; you lose Astro’s strongest feature.
  • Assuming Astro replaces a CMS — for non-technical editors you still need a CMS in front.
  • Hosting Astro on a server-heavy platform when static would be cheaper and faster.

Who this is for

Indie builders making content sites, documentation, marketing pages, or small portfolios.

When to skip this

Teams building dashboards, complex SaaS apps, or sites with deep client-side state and routing.

FAQ

  • Is Astro production-ready in 2026?: Yes. Astro has been stable for years, has a large plugin ecosystem, and powers many production content sites.
  • Can I use React inside Astro?: Yes, with the React integration. Islands render React components only where you opt in, keeping the rest of the page JS-free.
  • How does Astro compare to Hugo or Eleventy?: Astro is more flexible if you want JS components anywhere; Hugo is faster at build time for huge sites; Eleventy is the most minimal. Choose by ecosystem fit.
  • Does Astro work with Markdown / MDX?: Yes, natively. Content collections give you typed front matter on top of Markdown and MDX files.

Tags: #Indie dev #Astro #MDX #Comparison #Getting started

Related Articles