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:

DirectiveWhen the component hydratesTypical use
client:loadImmediately, as soon as the page loadsA search box or a menu that must work at once
client:idleWhen the browser is idleA secondary widget that can wait a moment
client:visibleWhen the component scrolls into viewA chart, a gallery, or an embedded demo
client:mediaWhen a media query matchesA mobile-only drawer or a print-specific widget
client:onlyOnly in the browser, never rendered on the serverA 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:

AspectAstroDocusaurusVitePressClassic static generator
Default outputStatic HTML, no client runtimeStatic HTML with a React runtime for navigationStatic HTML with a Vue runtimeStatic HTML
Component model.astro templates plus any framework componentReact onlyVue onlyTemplates or shortcodes
Content modelCollections with a validated schema, plus MDXFolders and sidebars, with versioningFolders and a sidebarMarkdown or templates
InteractivityIslands, hydrated one at a timeA single React applicationA single Vue applicationHand-written scripts
Extension modelIntegrations and server adaptersPlugins and themesVue plugin ecosystemBuild-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.

Found an issue with this content?

Tell us what could be improved.