Static Deployment

`npm run build` produces `dist/`. Drop it on Netlify, Vercel, Cloudflare Pages, GitHub Pages — anywhere that serves static files.

3 min read Level 1/5 #astro#deployment#static

What you'll learn

Build for production
Deploy via Git push or drag-and-drop
Configure the SPA fallback only if needed (rarely)

A statically built Astro site is just files. Any web host can serve them.

Build

npm run build       # outputs dist/
npm run preview     # serves dist/ locally to spot-check

dist/ contains pre-rendered HTML, optimized images, hashed JS bundles, and CSS.

Where To Deploy

Host	Approach
Netlify	Connect GitHub, auto-detect Astro, deploy
Vercel	Same — connect, auto-detect, done
Cloudflare Pages	Same — fastest edge network
GitHub Pages	Free for public repos. Needs `base` config if not at root
AWS S3 + CloudFront	Manual but full control
Static file server	Anything that serves `dist/` works

For Netlify / Vercel / Cloudflare, the typical flow:

Push to GitHub
New site → connect repo
Build command: npm run build, output: dist/
Deploy

GitHub Pages — Base Path

If your site lives at username.github.io/repo, set the base:

// astro.config.mjs
export default defineConfig({
  site: "https://username.github.io",
  base: "/repo",
});

All Astro-generated links pick up the base path.

404 Handling

src/pages/404.astro produces dist/404.html. Most static hosts serve it automatically when no route matches.

Cache Headers

Static hosts set sensible defaults: HTML is short-cached, hashed assets (*.js, *.css with content hashes) are long-cached. You usually don’t need to configure.

Trailing Slash

The default is “ignore” — both /about and /about/ work. You can enforce one with trailingSlash: 'always' | 'never' in astro.config.mjs.

Up Next

Deploying a server-rendered site.

Server Deployment →