How To Host An Astro Site Without A Server Adapter

Astro builds static by default, so you can host an Astro site anywhere with no adapter. When you do need one, the Node 22.23.4 trap, and a blog that rebuilds.
The OxyPages Team · · 8 min read
You've built a site with Astro, and now every hosting guide you open wants you to install an adapter first: @astrojs/netlify, @astrojs/vercel, @astrojs/node. It sounds like you can't host an Astro site without one.
For most Astro sites, you don't need any of them. Astro builds a fully static site by default. Run astro build and you get a dist folder of plain HTML, CSS and images that any static host can serve, with no adapter, no server and no Node process running anywhere. That's what a static website is, and it's Astro's default.
Adapters are for the other kind of Astro site, the one that renders pages on demand. That's a real feature and some sites need it. But if your blog, portfolio or docs site has none of the features in the checklist below, installing an adapter just ties you to one host for no reason.
I built a fresh Astro 7.4.7 project on 8 November 2026 to check what the defaults produce today, and hit a Node version error before anything else. Here's that error, what the build writes, how to tell whether you need an adapter, and how to keep a content-collection blog updating without a server.
TL;DR: Astro's output setting defaults to 'static', so npm run build writes a plain dist folder you can upload to any static host. No adapter is needed. You only need one if a page opts into on-demand rendering with export const prerender = false or the site uses output: 'server', which you'd do for cookies, request headers or server endpoints. Astro 7 needs Node 22.23.4 or newer. For a blog, every new post means a new build, so connect the repository to a host that rebuilds on push.
Do You Need An Adapter For Astro?
No, not for a static site, which is what Astro builds unless you tell it otherwise. The output option defaults to 'static', and Astro's docs describe that mode as prerendering every page and "outputting a completely static site if none of your pages opt out of prerendering."
You need an adapter in exactly one situation: when at least one page renders on demand, at request time, on a server. Astro's docs say on-demand rendering "requires a server adapter", and the official ones cover Node.js, Netlify, Vercel and Cloudflare.
My test confirmed the boundary. The default project built with no adapter. Then I added one page with export const prerender = false and the build stopped with:
[NoAdapterInstalled] Cannot use server-rendered pages without an adapter.
Please install and configure the appropriate server adapter for your final deployment.
So Astro tells you. If your build passes with no adapter in astro.config.mjs, your site is static and you can host it anywhere.
The Node Version Error You'll Hit First
Astro 7 requires Node 22.23.4 or newer, and it checks before it builds anything. My machine had 22.23.1, three patch releases behind, and npm run build printed this and quit:
Node.js v22.23.1 is not supported by Astro!
Please upgrade Node.js to a supported version: ">=22.23.4"
That's stricter than most tools, and it trips people up because 22.23.1 looks close enough. Astro's install guide also says odd-numbered Node versions like 23 aren't supported. The Node.js release schedule shows 22.23.4 is the latest 22.x release, alongside the newer 24 and 26 lines.
It matters twice: once on your machine, and again on any host that runs the build for you. Check which Node version your host's build image uses before you push, or the first deploy fails on a version check rather than your code.
What Does astro build Actually Produce?
astro build writes a dist folder with one HTML file per page, plus your assets. I gave the starter an about page and two blog posts from a dynamic route, and the build took 132 milliseconds:
dist/
index.html
about/index.html
blog/first-post/index.html
blog/second-post/index.html
favicon.ico
favicon.svg
Every page is real HTML. There's no single index.html that boots a JavaScript app, which is the big difference from a React or Vue build. Two things follow from that.
First, you don't need a single-page app fallback. Each URL has its own file, so refreshing /about just works on any host. Second, search engines and link previews see your full content with no JavaScript required.
The about/index.html layout comes from Astro's build.format option, which defaults to 'directory'. That gives clean URLs like /about/ on almost every host. Set it to 'file' if your host prefers about.html.
Which Astro Features Need A Server?

Anything that depends on the individual request needs a server and an adapter. Astro's on-demand rendering docs list these:
- Cookies through
Astro.cookies, reading or setting them - Request data through
Astro.request, like headers or the HTTP method - Response control through
Astro.response, like a custom status or a redirect computed per request - Server endpoints, the API routes in
src/pages/that return aResponseat request time - HTML streaming, sending the page in chunks as it renders
- Server islands, components marked
server:defer, which need an adapter even on an otherwise static site
What doesn't need a server is a longer list than people expect. Content collections, Markdown and MDX pages, dynamic routes with getStaticPaths, React or Svelte islands that run in the browser, and image optimisation all work in a static build.
That last one is worth a moment. Astro's <Image /> component optimises images from src/ at build time for prerendered pages, using Sharp by default. So you keep resized, modern-format images on a plain static host, which a Next.js static export can't do with its default loader. Images in public/ are copied as they are and never optimised, so keep photos in src/ if you want them processed.
One more thing that works statically but deserves care: environment variables. Astro uses Vite's system, so a variable prefixed PUBLIC_ is written into the code the browser downloads. Why your Vite environment variables are public explains the rule, and it applies here word for word.
Where Can You Host An Astro Site?
A static Astro build goes anywhere that serves files. The real choice is whether you need on-demand pages now or later.
| Host | Static Astro, no adapter | On-demand pages | Builds from Git |
|---|---|---|---|
| Netlify | Yes | Yes, with @astrojs/netlify | Yes |
| Vercel | Yes | Yes, with @astrojs/vercel | Yes |
| Cloudflare | Yes | Yes, with @astrojs/cloudflare | Yes |
| GitHub Pages | Yes, set site and base for a project site | No | Through GitHub Actions |
| OxyPages | Yes, upload dist or connect the repository | No | Yes |
The honest verdict: if you think you'll add server endpoints or per-visitor pages soon, start on Netlify, Vercel or Cloudflare, because switching adapters later is easy and switching hosts is not. If the site is content that changes when you publish, any row in that table works, and you can pick on price or convenience.
OxyPages fits that second case only. It serves the built files and never runs server code, so an Astro site with even one on-demand page needs one of the first three.
For a GitHub Pages project site, set site to https://username.github.io and base to /repo-name in astro.config.mjs, or your links and assets point at the wrong folder. On a host that gives each project its own subdomain, leave base unset.
Walkthrough: An Astro Blog That Rebuilds On Every Post

A content-collection blog is the most common Astro site, and it shows the one habit a static site needs: publishing a post means rebuilding.
- Write posts as Markdown in a content collection, like
src/content/blog/my-post.md. Astro turns each one into a page at build time. - Push the project to GitHub. Keep
distandnode_modulesin.gitignore. - Connect the repository to a host that builds on push. Set the build command to
npm run build, the output folder todist, and make sure the build uses Node 22.23.4 or newer. - Publish by pushing. A new Markdown file, a commit, a push, and the host rebuilds the site. For a small blog, the install step takes longer than the build itself.
- Use a deploy hook for a headless CMS. If posts live in a CMS instead of Markdown, most hosts that build from Git give you a deploy hook URL. Paste it into the CMS's webhook settings so publishing a post triggers a build.
- Check the live site for the new post, then check that an old URL still loads.
There's no server to keep running, nothing to patch, and the published site is just files. For a blog, that's a feature rather than a limitation. If you've also got a Vite app to put online, deploying a Vite app from its dist folder is the same idea with one extra setting.
What To Do Next
- Run
node -v. If it's below 22.23.4, upgrade before anything else. - Run
npm run build. If it passes with no adapter installed, your site is static. - Open
distand check there's an HTML file for each page you expect. - If any page uses cookies, request headers or server endpoints, pick Netlify, Vercel or Cloudflare and install that adapter.
- Otherwise, upload
distto any static host, or connect the repository so every push rebuilds.
If your site passed step 2, put your Astro build online with OxyPages by uploading dist or connecting the repository, with no adapter to install.
FAQ
Can I Host An Astro Site On GitHub Pages?
Yes, as long as it's static. Set site and, for a project site, base in astro.config.mjs, then build with GitHub Actions or commit the built files. GitHub Pages can't run on-demand pages, so any page with prerender = false won't work there.
Is Astro Static Or Server-Rendered By Default?
Static. The output option defaults to 'static', which prerenders every page to HTML at build time. You opt individual pages into on-demand rendering with export const prerender = false, or flip the default with output: 'server'.
Why Does My Astro Build Fail On The Host But Work Locally?
The most common cause in Astro 7 is the Node version. The host's build image may run an older Node than your machine, and Astro refuses to build below 22.23.4. Set the host's Node version, or check which one its build image uses, then rebuild.
Do Astro Content Collections Need A Database?
No. Collections read Markdown, MDX, JSON or YAML files from your project at build time and turn them into pages. Nothing is queried when a visitor loads the site, which is why you can host an Astro site built on collections on any static host.