How to host an Astro dist folder

To host an Astro dist folder, build the project so Astro writes static HTML to dist/, confirm every route was prerendered rather than left for a server, then zip the contents of dist and upload that archive to a static host. Astro prerenders your whole site by default, so a standard build is usually ready to serve as plain files.

Build, check the production output locally, then create the archive:

npm run build       # prerenders your site into ./dist
npm run preview     # serves the built dist locally so you can check it
cd dist
zip -r ../site.zip .

Upload site.zip and you have a URL. Before you do, check where Astro wrote the output, whether every route became a file, and why a page visible in development might be absent from dist.

Where Astro writes the build

npm run build compiles your project into static HTML and bundled assets. Astro's deployment guide describes this as building your site to static files by default, and it writes them to a dist folder in your project root.

That location isn't hard-coded. The outDir option sets the directory astro build writes to and defaults to ./dist. If your astro.config.mjs sets outDir to something else, the build lands there instead. Open the config before you go looking for the folder.

Run the build with whatever your lockfile points to: package-lock.json means npm run build, pnpm-lock.yaml means pnpm build, yarn.lock means yarn build, and bun.lock means bun run build. The output folder is the same either way.

What has to be true to host an Astro dist folder as static files

Astro's current output setting has two targets, static and server, and only a fully prerendered build produces something a file host can serve on its own. By default, Astro prerenders pages, routes, and endpoints at build time as static HTML. That's the output a ZIP host wants. The moment a route is set to render on demand, that route needs a server process, and no amount of zipping changes it.

Match what your project uses against this table:

If every row your project touches is a "Yes," the build is static and this workflow fits. A single "No" means that piece needs a runtime host, even when the rest of the site is plain HTML. For anything not listed, ask whether it runs while astro build is creating files or after a visitor requests a page. The framework-agnostic static-versus-dynamic guide applies that test to Next.js, Vite, and AI-builder exports.

Run the build and inspect dist

Don't upload a folder you haven't opened. After the build, look inside dist:

dist/
├── index.html
├── about/
│   └── index.html
├── blog/
│   └── first-post/
│       └── index.html
├── _astro/
│   ├── about.DpR2s9x1.css
│   └── client.Cb3f0aQ.js
└── favicon.svg

A few Astro specifics are worth recognizing here:

• Routes are folders, not flat files. Astro's default build.format is directory, so /about becomes about/index.html rather than about.html. A host that serves directory indexes returns the right page when someone visits /about.
• _astro/ holds the bundled CSS and JavaScript. That's Astro's default asset folder. A hashed filename changes when that bundled asset's contents change, which lets a new upload bypass stale copies of the old asset.
• favicon.svg sits at the root untouched. Files in your public/ directory are copied into the build as-is, without bundling.

Then preview it. npm run preview (which runs astro preview) serves the contents of dist locally so you can click through the exact files you're about to zip. Open the URL it prints, walk the routes, and watch the Network tab for failed asset requests. Astro is explicit that preview is for local inspection, not production hosting, so treat it as the last check before the upload rather than the deployment itself.

Why a route can be missing from dist

You see a page in npm run dev, build, and it isn't in dist. In static mode this almost always traces back to a dynamic route.

A file like src/pages/blog/[slug].astro doesn't know which slugs exist. Astro's static routing docs require a dynamic route to export a getStaticPaths() function so every path is known at build time:

---
export function getStaticPaths() {
  return [{ params: { slug: 'first-post' } }, { params: { slug: 'second-post' } }]
}
---

Astro builds one HTML file per object that function returns. A slug you forgot to include there simply doesn't get a page. If the route can't enumerate its paths ahead of time because it depends on request data, it isn't a static route at all, and it belongs in the on-demand category from the table above.

Choose a runtime host when Astro needs an adapter

If the table turns up an on-demand feature, stop before packaging dist. Add the adapter for your destination and deploy through that platform's Astro workflow instead. An adapter can still write files into the output directory, but those files include code for a server, serverless function, or edge runtime. A static ZIP host cannot execute them.

The dividing line is whether part of the app runs code for each visitor. A static frontend can call a separately hosted API over the network, but the server-rendered part of an Astro app has to run somewhere that executes it.

A note on the base path

Astro serves your site from the domain root by default, and PreviewSend serves the build so that default is correct. If you set base to a subpath for a different host, Astro expects you to prefix your own internal links and asset URLs with that base. Set base, update hand-written links to use that prefix, then rebuild so the corrected paths are written into dist. The Vite dist-folder guide covers the same subpath trap in more depth if you're comparing the two build tools.

Zip the contents, then upload

Package the build so index.html lands at the top of the archive:

cd dist
zip -r ../site.zip .

The trailing . compresses the folder's contents, not the folder itself. Without a terminal, open dist, select everything inside, and compress the selection. Keeping index.html at the archive root is the most portable layout. PreviewSend can use the shallowest nested index.html, but other hosts may be stricter; the ZIP hosting guide covers the layout checks behind "index.html not found" errors.

With site.zip holding a root index.html, the upload is short. Static hosts that accept prebuilt files directly, without a repository or CI pipeline, include Cloudflare Pages Direct Upload and Netlify Drop; their access controls and limits vary. For a client-facing draft that needs a stable review URL, start a PreviewSend workspace and upload the archive (up to 100 MB compressed and 256 ZIP entries). It validates the ZIP, extracts the files, serves the nested route directories your Astro build produced, and returns a stable URL. It does not execute Astro server code, so an on-demand route from the table above still won't run.

Because the URL is stable, updating the site means rebuilding, re-zipping dist, and uploading again. The new build becomes the active version at the same address, so everyone holding the link sees the current site without a new attachment. New projects also turn on account-free review by default: a reviewer can pin comments or request changes on the page without a PreviewSend account. If the draft needs to stay private, add a project password, which is the actual access gate. A noindex header asks search engines to stay away, but it's a request, not access control, so anyone with the link can still open an unprotected preview.

Before you send the link, open a nested route such as /about, reload it directly, and check the browser's Network tab once more. That catches the two failures a homepage-only check misses: directory routes that return 404 and _astro assets requested from the wrong path.