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.
- 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.
---
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> ---
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>} 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
- 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
- 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.
BetterCMS for Astro teams
This page is served from an Astro build, so the fit is not theoretical. These are the parts an Astro project uses.
-
A client that suits a build
Workspace-scoped, read on the server, and able to page through a whole collection in one pass.
-
Hosting that rebuilds for you
Run the Astro build yourself, or let BetterCMS Cloud host the site and rebuild it on publish.
-
Blocks that map to components
A page returns a list of typed blocks, which is the same shape an .astro layout already walks, and the Astro package ships a renderer for it.
-
Editing on the built page
Marketers change copy and sections on the rendered Astro site rather than in a form.
-
Markdown twins and llms.txt
Pages are also published as markdown with an llms.txt index, so an answer engine reads content rather than layout.
-
Forms and search included
The two runtime features a static Astro site normally needs a second vendor for. The Astro package loads forms for you.
-
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.