Introduction to Astro
Astro is a web framework for content-driven sites: documentation, marketing pages, blogs, and anything else where most of the page is text and a small part of the page is interactive. It is not a component framework in the usual sense. You do not build the whole page out of components and hand it to a runtime; instead you write a template, and the framework renders it to HTML when you run the build. The browser receives a document, not an application.
That single decision produces most of Astro’s characteristics. Because rendering happens at build time, there is no hydration cost for content that never changes, the output is a folder of static files that any host can serve, and the first paint does not wait for a framework to boot. Because a template is just a file, the same file can hold a small script for data it needs and a scoped stylesheet for the markup it owns, and neither leaks into the rest of the site. Because the framework is not in charge of the whole page, a component written in React, Vue, Svelte, Preact, Solid, or Lit can be dropped into the template without adopting that framework for the rest of the page.
A .astro file is the unit of work. Everything before the closing fence of the frontmatter block runs on the server at build time, and everything after it is the template:
---
// src/components/Note.astro
interface Props {
title: string;
tone?: 'info' | 'warning';
}
const { title, tone = 'info' } = Astro.props;
---
<aside class={`note note--${tone}`}>
<strong>{title}</strong>
<slot />
</aside>
<style>
.note {
border-inline-start: 3px solid currentColor;
padding-inline-start: 1rem;
}
.note--info {
color: #0b6bcb;
}
</style>
The styles are scoped automatically. Astro adds an attribute to the elements in the template and rewrites the selectors in the style block to match, so .note in this file cannot leak into another component. Adding is:global to a style block opts out of that, and is:global on a single selector opts out for that rule only.
The second idea is the island architecture. An island is an interactive component that is rendered to HTML on the server and then, optionally, hydrated in the browser as an independent unit. The hydration strategy is chosen with a client directive, and the directive is the single most important decision you make about a component’s cost:
| Directive | When the component hydrates | Typical use |
|---|---|---|
client:load | Immediately, as soon as the page loads | A search box or a menu that must work at once |
client:idle | When the browser is idle | A secondary widget that can wait a moment |
client:visible | When the component scrolls into view | A chart, a gallery, or an embedded demo |
client:media | When a media query matches | A mobile-only drawer or a print-specific widget |
client:only | Only in the browser, never rendered on the server | A component that depends on browser-only APIs |
A component without a directive is rendered to HTML and shipped as markup only. That is the default, and it is the reason a documentation site built with Astro usually transfers a very small amount of JavaScript even when it contains several interactive pieces.
Framework components are used in exactly the same way. Once the React integration is installed, a .jsx file can be imported into a template and given a directive:
---
import SearchBox from '../components/SearchBox.jsx';
import Counter from '../components/Counter.vue';
---
<SearchBox client:load />
<Counter client:visible />
Several frameworks can coexist on the same page, each with its own island. The practical rule is that a framework is a delivery mechanism for a component, not a decision about the site. Using React for a form that already exists in React and Svelte for a chart that already exists in Svelte is a normal, supported arrangement.
Content is the other half of the framework. Astro reads Markdown and MDX files from the filesystem and exposes them through content collections, where each collection has a schema that is validated at build time. A missing title or an unparseable date fails the build instead of shipping a broken page. The MDX integration extends that to allow components inside a Markdown file, and the Starlight theme builds a complete documentation site — sidebar, navigation, search, dark mode, internationalisation — on top of those primitives.
Rendering is configurable. The default output is static, which produces a folder of files that can be hosted anywhere. A project can also be configured for server output with an adapter, and in that mode individual routes can opt back into static generation by exporting a prerender flag. The mode that existed separately as “hybrid” in earlier versions was folded into server output, where each route declares its own nature.
// src/pages/dashboard.astro
export const prerender = true;
A configuration file ties the integrations together:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import react from '@astrojs/react';
export default defineConfig({
site: 'https://docs.acme.dev',
integrations: [mdx(), sitemap(), react()],
markdown: {
shikiConfig: { theme: 'github-dark' },
},
});
Placing the framework against its peers clarifies the trade:
| Aspect | Astro | Docusaurus | VitePress | Classic static generator |
|---|---|---|---|---|
| Default output | Static HTML, no client runtime | Static HTML with a React runtime for navigation | Static HTML with a Vue runtime | Static HTML |
| Component model | .astro templates plus any framework component | React only | Vue only | Templates or shortcodes |
| Content model | Collections with a validated schema, plus MDX | Folders and sidebars, with versioning | Folders and a sidebar | Markdown or templates |
| Interactivity | Islands, hydrated one at a time | A single React application | A single Vue application | Hand-written scripts |
| Extension model | Integrations and server adapters | Plugins and themes | Vue plugin ecosystem | Build-time plugins |
Astro is a poor fit when the entire site is a dashboard behind a login, because there is nothing static to render and the framework’s advantage disappears. It is also a poor fit if the team has no appetite for a component model of its own, because .astro files are a new thing to learn. For a content site that needs a handful of interactive islands and a fast static delivery, it is one of the most direct options available, and the pages that follow show how to use it.
