What Is Astro? The Content-First Web Framework

Astro is a web framework for building content-first sites — blogs, documentation, marketing pages, portfolios — that ship almost no JavaScript to the browser. It is the framework this site is built on, and this post explains what it is, why it exists, and where it shines.

No prior framework experience is required.

What is Astro?

Astro is an open-source web framework focused on content-driven websites. It was created in 2021 and the current major version is Astro 5, released in late 2024. Astro is what powers a large share of modern documentation sites, including official docs for many of the tools you already use.

The smallest possible Astro page looks like this:

---
const name = "world";
---
<h1>Hello, {name}!</h1>

That is a file in src/pages/. The block between the --- fences is JavaScript that runs at build time. Everything below is the HTML the visitor receives. There is no client-side JavaScript involved unless you opt in.

The problem Astro was designed to solve

Most modern frameworks — React, Vue, SvelteKit — were built around interactive single-page applications. They ship a JavaScript runtime to every visitor, hydrate the page, and only then can it respond to input. For a Gmail-style app, that trade-off is correct. For a blog, it is wasteful.

A typical content site has:

• Pages that are almost entirely static
• A small island of interactivity here and there — a search box, a theme toggle
• A heavy reliance on Markdown, MDX, or a headless CMS

Astro looks at that shape of site and asks an obvious question: why send a SPA runtime at all? Render the page to HTML at build time, ship the HTML, and only hydrate the small interactive pieces that genuinely need JavaScript.

That model is what Astro calls the islands architecture, and it is the single most important idea in the framework.

Zero JavaScript by default

Open the network tab on a typical Astro blog post and you will see one HTML file, some CSS, maybe a font — and no JavaScript bundle. Not a small one. None at all.

This is not an optimisation you turn on. It is the default. JavaScript only appears when you explicitly add an interactive component and mark it with a client: directive.

---
import Counter from '../components/Counter.jsx';
---
<h1>My blog post</h1>
<Counter client:load />

In that example, the heading is plain HTML. The counter is a React component that hydrates in the browser. Everything else on the page stays static. We cover this in depth in Astro Islands.

The core ideas of Astro

You only need a handful of concepts to read most Astro code.

1. .astro components

The native component format. Frontmatter for build-time JavaScript, an HTML-like template below.

---
const title = "Hello";
---
<h1>{title}</h1>

2. File-based routing

Files in src/pages/ become routes. src/pages/about.astro is /about. src/pages/blog/[slug].astro is /blog/anything. No router configuration required.

3. Content collections

A type-safe way to manage Markdown and MDX. You define a schema in src/content/config.ts and Astro validates every file against it.

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    publishedAt: z.date(),
  }),
});

export const collections = { blog };

We cover this in Astro Content Collections.

4. MDX

Markdown with components mixed in. Astro treats MDX as a first-class citizen — you can import an Astro or React component and drop it into a blog post.

5. Islands

Interactive components from React, Vue, Svelte, Solid, or Preact, embedded into otherwise-static pages and hydrated on demand.

When Astro is the right tool

Astro fits a specific shape of project very well.

• Blogs and personal sites — fast, simple, and the Markdown story is excellent
• Documentation sites — Starlight, the official docs theme, is built on Astro
• Marketing pages — landing pages, product pages, anything heavy on copy
• Portfolios — image galleries, case studies, designer sites
• E-commerce storefronts with mostly static product pages and a small cart island

If your site is mostly content with a sprinkle of interactivity, Astro is hard to beat. The performance ceiling is very high because you are shipping the bare minimum.

When Astro is not the right tool

Astro is honest about what it is not.

• Highly interactive SPAs — Gmail, Figma, a Trello clone. Use Next.js, SvelteKit, or plain React.
• Real-time dashboards that update constantly from a socket. The static-first model fights you.
• Apps where every page is behind login and content is dynamic per user. You can do it, but a SPA framework is a better fit.

A useful test: if more than half of your pages would need client:load on most of their content, Astro is probably the wrong tool. Pick a framework designed for that workload.

How Astro compares to other tools

You will hear four other names in the same conversation.

• Next.js — full React framework, excellent for apps. Heavier runtime, more complex mental model.
• SvelteKit — Svelte’s full framework. Smaller bundles than Next, more app-shaped than Astro.
• Eleventy — a venerable static site generator. No components-from-React story; pure templating.
• Hugo — Go-based static generator. Blisteringly fast builds, no JavaScript story at all.

Astro’s sweet spot is content sites that occasionally need a React, Vue, or Svelte component. Eleventy and Hugo cannot do that elegantly. Next and SvelteKit can, but they pay the SPA tax on every page.

What you can build with Astro

A realistic progression for a beginner:

Within your first week:

• A personal blog with Markdown posts and an RSS feed
• A multi-page marketing site for a small project
• A documentation site using Starlight

Within a month:

• A blog with type-safe content collections, dynamic routes, and tag pages
• A portfolio with image optimisation and a contact form
• A docs site with versioned content and a search island

Within three months:

• A storefront with static product pages and a hydrated cart
• A content site backed by a headless CMS like Sanity or Contentful
• A custom integration that extends Astro itself

None of this requires a React background — Astro’s own component model is enough.

Modern Astro vs older Astro

Astro changed shape twice between 2021 and 2024. The version that matters today is Astro 5 and onwards, which introduced:

• Stable content layer with the new loader API
• Server islands for streamed dynamic content
• A redesigned config experience
• First-class TypeScript across the board

This series teaches Astro 5 only. If a tutorial uses getStaticPaths without typed collections or pre-content-collections frontmatter, it is older code. You can read it; do not copy it verbatim.

What you need to get started

To follow the rest of this series you need:

1. A computer running Windows, macOS, or Linux
2. Node.js 20 or newer — covered in the next post
3. A modern browser
4. A code editor — VS Code has an excellent official Astro extension
5. Comfort with HTML and basic JavaScript

You do not need React experience, a CSS framework, or any paid tools.

Recap

You now know:

• Astro is a content-first web framework that ships zero JavaScript by default
• Pages are .astro files with build-time frontmatter and an HTML template
• Routing is file-based out of src/pages/
• Content collections give you type-safe Markdown and MDX
• Islands let you embed React, Vue, or Svelte components that hydrate on demand
• Astro fits blogs, docs, and marketing — not highly interactive SPAs

Next steps

The next post walks through installing Astro, scaffolding a project, and building your first page in about ten minutes.

→ Next: Install Astro and Build Your First Page

Questions or feedback? Email codeloomdevv@gmail.com.