Astro

What is Astro?

Astro is an open source web framework for content-driven websites. Astro renders pages to HTML at build time or on the server and ships no JavaScript to the browser unless a component explicitly asks for it. Pages are written as .astro components, and React, Vue, Svelte and Solid components can be used in the same project.

The design goal is that a page of text should cost a page of text. Most frameworks send a JavaScript runtime and re-render the page in the browser to show a paragraph. Astro sends the paragraph, and reserves JavaScript for the parts that genuinely need it.

A card stating the default for every Astro page — static HTML, with no JavaScript in the browser — above a horizontal axis labelled "when an island hydrates". Four ticks on the axis carry the four client directives and what each one waits for: client:load at once, client:idle when the browser is free, client:visible when it scrolls into view, and client:media at a screen width. Everything else on the page stays static HTML. CLIENT DIRECTIVES Nothing hydrates until a component asks EVERY PAGE, BY DEFAULT Static HTML. No JavaScript in the browser. WHEN AN ISLAND HYDRATES client:load at once client:idle when the browser is free client:visible when it scrolls into view client:media at a screen width Everything else on the page stays static HTML.
What it is
A web framework for content-driven sites.
Default output
Static HTML, with no client JavaScript.
Components
.astro files, plus React, Vue, Svelte or Solid.

How does Astro work?

An .astro file has two parts. A frontmatter block at the top runs on the server, where it can read files, call an API and await anything. A template below it produces HTML. The frontmatter never reaches the browser, so a page can fetch from a CMS with a secret key and still ship as a static file.

Interactive components are opt-in and are called islands. A component marked with a client directive is hydrated in the browser and the rest of the page stays static HTML. The directive also decides when: on load, when the browser is idle, when the component scrolls into view, or only at certain screen widths.

Astro builds to static files by default. Adding an adapter switches a project, or a single route, to server rendering.

  • Frontmatter runs on the server. Fetches, secrets and file reads never reach the client.
  • Islands are opt-in. A page with no interactive component ships no JavaScript.
  • Any UI framework. React, Vue, Svelte and Solid components work in one project.
  • Static or server rendered. Per project, or per route with an adapter installed.

What is Astro good at?

Pages that are mostly text and images. Marketing sites, documentation, blogs, changelogs, landing pages and storefront pages are the shape Astro was built for, and they are the shape where sending no JavaScript is a real advantage rather than a slogan.

It is also good at incremental adoption. Because any framework component can be dropped into an .astro page, a team can keep an existing React component library and stop shipping the runtime on the pages that do not use it.

Where does content come from in Astro?

Astro content collections read Markdown and MDX files from the repository, validate them against a schema, and give the results types. For content written by the people who write the code, that is usually the whole answer.

Astro 5 widened collections so a loader can pull from a remote source as well as from disk, which lets CMS content sit inside the same typed collections API as the local files.

Beyond that, an Astro page can call any API from its frontmatter. A headless CMS is simply one of those APIs, and because the call runs during the build the visitor is still served static HTML.

A CMS entry on an Astro page

Frontmatter reads the CMS, the template renders it, and the browser gets HTML.

Every BetterCMS symbol here is from the published @bettercms-ai/sdk. The export is BetterCMS and the client is BetterCMS.site({ workspace }), with apiKey added when the read needs one. getContent returns a page whose entry carries the fields, listContent pages through a collection and reports hasNextPage, and listContentAll iterates the whole set. An Astro project would normally install @bettercms-ai/astro instead, which wraps all of this.

src/pages/index.astro
---
import { BetterCMS } from '@bettercms-ai/sdk';

const client = BetterCMS.site({ workspace: 'my-workspace' });

// Server-side. The key never reaches the browser.
const page = await client.getContent('home');
---

<h1>{page.entry.title}</h1>
src/pages/blog/index.astro
---
import { BetterCMS } from '@bettercms-ai/sdk';
import PostCard from '../../components/PostCard.astro';

const client = BetterCMS.site({
  workspace: 'my-workspace',
  apiKey: import.meta.env.BETTERCMS_API_KEY,
});

const { items, hasNextPage } = await client.listContent({
  page: 1,
  perPage: 20,
});
---

<ul>
  {items.map((item) => <li><PostCard entry={item} /></li>)}
</ul>

{hasNextPage && <a href="/blog/2">Older posts</a>}
Terminal
bun add @bettercms-ai/sdk

# Point an assistant at the same workspace.
npx @bettercms-ai/mcp

When Astro is the wrong tool

Astro optimises for pages that are read. That is a real choice, and it costs something on the other side.

Pick something else

4 points
  • An application, not a site A dashboard or an editor is interactive everywhere, and islands stop helping.
  • Shared client state across the page Islands are separate roots. Passing live state between them is work you do yourself.
  • A team standardised on one framework If everything is React and everyone knows it, a second component model is friction.
  • Heavy per-user rendering A page that is different for every visitor gives up the static output entirely.

Astro fits

4 points
  • Content sites Marketing pages, documentation, blogs and changelogs.
  • A performance budget Static HTML at the edge, with interactivity added one island at a time.
  • Mixed component libraries React and Svelte in one project, without shipping both runtimes everywhere.
  • Content that a CMS owns Frontmatter can await an API, so a build-time fetch is one line.

Astro questions

The ones asked before a team commits to the framework.

  • Astro is used for content-driven websites: marketing sites, documentation, blogs, changelogs and storefront pages. Astro renders those pages to HTML at build time or on the server and sends no client JavaScript unless a component opts in.

  • Neither is better in general. Astro is built for pages that are mostly read and defaults to zero client JavaScript. Next.js is built for React applications and assumes React is running in the browser. A documentation site is usually a better fit for Astro, and a logged-in product for Next.js.

  • Astro can, but it does not require it. Pages are written as .astro components, and React, Vue, Svelte or Solid components can be added where interactivity is needed. Only the components marked with a client directive send their framework to the browser.

  • An island is an interactive component on an otherwise static page. Astro renders the page to HTML, then hydrates only the components marked with a client directive, so the JavaScript cost of a page is the cost of its islands rather than of the whole page.

  • Yes. Astro builds to static files by default, and installing an adapter switches a project, or an individual route, to rendering on each request. The two can be mixed in one site.

  • Astro helps in two specific ways. Pages are HTML by default, so a crawler gets the content without executing JavaScript, and the low client payload makes the loading metrics easier to pass. Neither of those decides ranking on its own.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.