
Astro is an open-source web framework for content-driven websites: blogs, marketing sites, documentation and publications. It turns your pages into plain HTML when the site is built and sends JavaScript to the browser only for the parts that need it. Choose Astro when a site is mostly content and speed matters. Look elsewhere when the "site" is really a logged-in application, or when your editors depend on WordPress plugins you are not ready to replace.
We build on Astro at Seahawk. This site, seahawkmedia.com, is an Astro site with more than 20,000 pages, so what follows comes from running one in production.
How Astro works, in three ideas
1. Pages are HTML by default
In many JavaScript frameworks, the browser downloads an application and assembles the page on your visitor's device. Astro does that work in advance. By default every page is pre-rendered at build time, so running astro build produces a dist/ folder of finished HTML, CSS and images that any web host can serve.
2. Interactivity is added in islands
A menu, a search box or a pricing calculator still needs JavaScript. In Astro you mark those components one at a time, and each becomes an "island" of interactivity on an otherwise static page. The components can be written in React, Preact, Svelte, Vue or Solid, and a directive controls when each one loads:
<!-- loads as soon as the page does -->
<SearchBox client:load />
<!-- loads only when it scrolls into view -->
<PricingCalculator client:visible />
Leave the directive off and Astro renders the component to HTML and strips its client-side JavaScript. That is why Astro pages tend to be light: you pay for interactivity only where you asked for it. The islands documentation covers the full set of directives.
3. A server is optional
Some pages cannot be built in advance: a logged-in dashboard, a cart, a search results page. For those, Astro can render on demand. You add an adapter for your host (Astro maintains official ones for Cloudflare, Netlify, Node.js and Vercel) and opt a page out of pre-rendering with one line at the top of the file:
---
export const prerender = false;
---
Every other page stays static. You can also flip the default with output: 'server' in the config and pre-render only selected pages.
What an Astro project looks like
Astro needs Node.js on the machine that builds the site. Current Astro 7 releases require Node.js 22.23.4 or later. A new project starts with one command:
npm create astro@latest
From there, npm run dev starts a local preview at http://localhost:4321 and npm run build writes the finished site to dist/.
Pages live in src/pages/ as .astro files. An .astro file is HTML with a small script block at the top, and any valid HTML is valid Astro template syntax, so a front-end developer can read one on day one.
Content usually lives in content collections: folders of Markdown files, or data loaded from an API, that Astro checks against a schema you define in src/content.config.ts. If a post is missing its title or has a malformed date, Astro reports an error instead of quietly publishing a broken page.
Where the content comes from
Astro is not a CMS. There is no login screen for editors. You decide where content is written, and Astro reads it when the site builds or when a page is requested.
| Content source | How editors work | Good for |
|---|---|---|
| Markdown files in the project | In a code editor, through Git | Developer-run blogs and documentation |
| WordPress as a headless CMS | In the WordPress admin they already know | Teams that want to keep WordPress for editing |
| EmDash | In a WordPress-style admin built for Astro | New content sites that want the CMS and front end in one project |
| Another headless CMS or API | In that tool | Organizations with an existing content platform |
Our guide to using Astro with WordPress walks through the headless route, and the EmDash page explains the CMS that was built for Astro.
When to choose Astro
- The site is mostly content. Articles, service pages, landing pages, case studies, documentation.
- Page speed and search visibility are business goals. Pre-built HTML with little JavaScript is a strong starting point for both.
- A developer or agency partner will own the code. Astro is a developer tool, not a site builder.
- You want to keep your CMS but replace a slow or fragile front end. WordPress can stay as the place content is edited.
- You want simple hosting. A pre-built Astro site is a folder of files, with no database or PHP facing the public.
When Astro is the wrong choice
- The product is an application. If nearly every screen is interactive and sits behind a login, a framework designed for web apps fits better. Our Astro and Next.js guide covers that decision.
- You want to build and run the site yourself without a developer. WordPress with a good theme is still the easier path. See WordPress vs Astro for the full decision matrix.
- The site depends on WordPress plugins for core features. Stores, memberships and bookings need a rebuild or a replacement service before a move makes sense.
- Nobody will maintain the code. An Astro site has fewer moving parts than a plugin-heavy WordPress site, but upgrades still need a developer.
| Type of site | Astro fit | Why |
|---|---|---|
| Company blog or publication | Strong | Pages are pre-built; content lives in collections or a CMS |
| Marketing site with a few forms | Strong | Static pages plus a handful of islands |
| Documentation | Strong | Markdown-first, with schema checks on every page |
| Online store | Possible | Needs on-demand rendering and a separate commerce back end |
| Logged-in web application | Weak | Most screens are interactive, so an app framework suits it better |
What agencies should know before selling it
Licensing and ownership. Astro is MIT-licensed. In January 2026 the company behind Astro joined Cloudflare. Astro stayed open source with open governance, and it continues to support many deployment targets, so a client site is not tied to one host.
Hosting. Static output runs on any static host or CDN. On-demand pages need a host with an adapter. We deploy this site to Cloudflare Workers from a CI job on every push to the main branch. Our list of Astro web hosts covers the options.
Skills. Astro uses HTML, CSS, JavaScript and TypeScript. A WordPress agency's front-end developers can pick it up without learning a new language, and a headless WordPress build is a natural first project. Our guide to offering Astro services covers positioning and pricing.
Upgrades. One command updates Astro and its official integrations together:
npx @astrojs/upgrade
Major versions do bring breaking changes. Astro 7 moved to Vite 8 and to a stricter compiler that reports an error on unclosed HTML tags instead of silently correcting them. Budget time for each major upgrade the way you would for a major WordPress or PHP version.
How to try Astro on your own machine
- Check your Node.js version with
node --version. You need 22.23.4 or later. - Create a project from the official blog example:
npm create astro@latest -- --template blog. - Run
npm run devand openhttp://localhost:4321. - Edit one of the Markdown posts in the project and watch the page update.
- Run
npm run buildand open thedist/folder. Those files are the whole website.
That last step is the one that makes Astro click for most site owners: what you deploy is ordinary HTML that you can open and read. The Why Astro page in the official docs lays out the design principles behind it.
Frequently asked questions
Is Astro a CMS?
No. Astro builds and renders pages, and it has no admin screen for editors. Content comes from Markdown files in the project or from a CMS such as WordPress or EmDash that Astro reads from.
Is Astro free?
Yes. Astro is open source under the MIT license. Your costs are development time and hosting.
Does Astro replace WordPress?
It can replace the WordPress theme while WordPress stays as the editor, or replace WordPress entirely on a content site. It does not replace plugin-driven features such as WooCommerce on its own.
Do I need to know React to use Astro?
No. Astro components are HTML with a script block. React, Vue, Svelte and the other frameworks are optional, and you only reach for them when a component needs to be interactive.
