T1 — Beginner · Single Page What Is Astro?
A gentle introduction

Meet Astro — the framework built for the web you already know

No prior framework experience needed. By the end of this page you'll know exactly what Astro is, what it does, and whether it's the right tool for what you want to build.

Why this matters

You don't need a bulldozer to plant a flower

Most websites are simple things: text, images, maybe a contact form. But over the last decade, developers started building even the simplest sites with enormous, complex tools — the same kind of machinery used to build Gmail or Google Maps. The result? Sites that take several seconds to load, for no good reason.

Astro is a reaction to that. It asks a simple question: what if your website just… sent HTML? No extra machinery. No unnecessary code running in your visitor's browser. Just the finished page, delivered fast.

⚡ Why it matters to you

If you're building a personal site, a portfolio, a blog, or a project page — you don't need a complex app framework. Astro is purpose-built for exactly this. Fast by default, beginner-friendly, and built around the HTML you already know.

Step back first

What even is a web framework?

Before we talk about Astro specifically, let's make sure "framework" makes sense.

Analogy

Imagine you're building a house. You could fell your own trees, mill your own lumber, smelt your own nails. But you probably won't — you'll buy pre-cut materials, use standard tools, follow established plans.

A web framework is the same idea. It's a set of pre-built solutions for common web development problems — routing, building, templating — so you don't have to solve those from scratch every time.

Without a framework, building even a small website with multiple pages means writing a lot of repetitive plumbing code. A framework handles that plumbing so you can focus on the content.

Common frameworks you might have heard of: Next.js, Gatsby, SvelteKit. Astro is one of these — but with a very different philosophy from the rest.

The main event

So what makes Astro different?

Most JavaScript frameworks share a hidden assumption: your browser should build the page. They ship code to your visitor's browser, and that code constructs the page on arrival — running calculations, fetching data, assembling what you eventually see.

For complex web apps — think dashboards, social feeds, email clients — this makes sense. The page needs to be constantly alive and reactive.

But for a blog post? A portfolio? A documentation page? There's nothing to react to. The content doesn't change between visits. Astro's big idea is to build the page once — ahead of time — and just send the finished result.

Analogy

Other frameworks are like a restaurant that sends you raw ingredients and a recipe — you cook at the table. Astro is the restaurant that sends you the finished meal. Your browser has nothing to do except display it.

The technical term for this is static site generation. Astro builds all your pages into finished HTML files when you run a build command. When a visitor loads your site, they get that pre-built HTML — which loads almost instantly, with no JavaScript required.

💡 Mental model

Think of an Astro build like printing a book. All the thinking happens before the book reaches the reader. The reader just reads — they don't have to process anything.

The file format

What is a .astro file?

When you build with Astro, you write .astro files. They look almost exactly like HTML files — because they mostly are HTML files — with one addition: a notes section at the top.

That notes section is called the frontmatter, and it's fenced off with three dashes on each side. Think of it as the "backstage" area of your page — a place to prepare things before the audience sees them.

my-page.astro
---
// Everything in here runs before the page is built.
// Fetch data, import components, define variables.
const title = "Hello, world!";
---

<!-- Everything below is normal HTML -->
<html lang="en">
  <body>
    <h1>{title}</h1>
    <p>This is my Astro page.</p>
  </body>
</html>

Notice {title} in the HTML — that pulls in the variable you defined upstairs. That's the main superpower of .astro files over plain .html files: you can use logic and variables to build your page, without shipping that logic to your visitors.

Frontmatter — between the --- fences
Runs at build time only. Never shipped to the browser. This is where you import components, fetch data, define variables.
Template — the HTML below
Standard HTML with {expressions} sprinkled in. This becomes the finished HTML your visitors receive.
<style> — optional
CSS that Astro automatically scopes to this file. Styles here won't accidentally affect other pages.
One more idea

What if part of your page does need to be interactive?

Astro ships zero JavaScript by default. But what if you need a working contact form? A live search box? An interactive map?

Astro handles this with a concept called Islands. The idea is simple:

Analogy

Imagine a mostly-static newspaper. 99% of it is ink on paper — you can't interact with it. But imagine there's a pull-out crossword puzzle in the middle: interactive, fillable, separate from the rest.

That crossword puzzle is an Island. Astro lets you build pages that are mostly static — fast, simple HTML — with one or two interactive islands exactly where you need them. Only those islands load any JavaScript.

You don't need to think about this right now. When you're just getting started with Astro, you'll likely build fully static pages and never need an Island. But it's good to know the option exists for when your projects grow.

→ Good to know

Astro's Islands work with React, Vue, Svelte, and other popular UI libraries — so if you learn one of those later, Astro can use it. You're not locked into one ecosystem.

The honest guide

Is Astro the right tool for you?

Astro is an excellent choice for a wide range of projects — but it's not the right tool for everything. Here's a plain-English breakdown:

Astro is great for

  • Personal websites and portfolios
  • Blogs and writing sites
  • Documentation and guides
  • Marketing and landing pages
  • Sites where speed and simplicity matter

Maybe not yet for

  • Apps with user login and accounts
  • Real-time features (chat, live feeds)
  • Complex dashboards with lots of user data
  • E-commerce with a custom cart
⚠️ A note on "not yet"

The "maybe not yet" list isn't a permanent wall — Astro supports server-side rendering and can handle more complex scenarios as you grow. But for your first Astro project, staying in simple, static territory is the right call.

Before you go

The short version

Here are the five things worth holding onto from this page:

Key takeaways
Web framework A toolkit of pre-built solutions so you don't rebuild common plumbing from scratch every project.
Astro A framework that builds your pages into plain HTML at build time — no JavaScript shipped unless you ask for it.
.astro file An HTML file with a frontmatter section (the --- block at the top) for logic that runs before the page is built.
Islands Optional interactive components in an otherwise static page. Only the islands load JavaScript — nothing else does.
Best for Content-first sites: portfolios, blogs, docs, marketing. Anything where your visitors are mostly reading, not interacting.

Ready to go deeper? The Astro Framework tutorial on this site covers the same territory at an intermediate level — with all the technical detail, comparisons, and edge cases included.