Deployment & Ecosystem

The production build

astro build produces your deployable output in dist/. What ends up there depends on your rendering mode:

Static — dist/ is a folder of .html files, CSS, and island JavaScript. It’s just files.
On-demand / hybrid — dist/ also contains a server entry in the format your adapter targets (a Cloudflare Worker, a Node server, a serverless function), plus the static assets.

Wire type-checking into the build so a type error stops a bad deploy: astro check && astro build.

Two deploy targets

The single biggest deploy decision is static vs on-demand — it determines where you can host:

	Static	On-demand (SSR)
Output	HTML files	Server entry + assets
Needs	Any static host / CDN	A runtime (via an adapter)
Hosts	Cloudflare Pages, Netlify, GitHub Pages, S3, any CDN	Cloudflare Workers, Node server, Vercel, Netlify Functions
Best for	Content that’s the same for everyone	Per-request data: auth, forms, live data
Adapter	Not required	Required

A purely static site deploys anywhere that serves files. The moment any route is on-demand (or uses server islands or Actions), you need the matching adapter configured — deploying without it is the classic “an adapter is required” error.

flowchart TB
  build["astro build"] --> static["Static: HTML files"]
  build --> ssr["On-demand: server entry + assets"]
  static --> cdn["any CDN / static host"]
  ssr --> runtime["adapter runtime: Workers, Node, serverless"]

Where a build can go

Set site and base correctly

Two config values bite people at deploy time:

site must be your real deployed URL (e.g. https://example.com). Sitemaps, canonical tags, and RSS all build absolute URLs from it — wrong site, wrong links.
base must match the subpath you’re served from. Deploy to example.com/docs/ and you set base: '/docs', then reference internal links with the base prefix. Serve at the domain root and you omit it. A mismatched base is the usual cause of “the deployed site’s CSS and links are all 404” — the assets are looked up at the wrong path.

The ecosystem

Astro is content-first, and its ecosystem reflects that:

Starlight — an official documentation-site framework built on Astro (it’s what this course is built with): sidebars, search, i18n, and dark mode out of the box.
Integrations directory — a large catalog of official and community integrations: UI frameworks, CMS connectors, image services, analytics, and adapters for every major host.
Content-focused patterns — combined with content collections, Astro is a natural fit for blogs, docs, marketing sites, and headless-CMS front-ends, where you get a fast static (or hybrid) site with typed content.

Reach for a framework like Starlight when it matches your use case rather than rebuilding docs infrastructure by hand — the same “compose, don’t reinvent” instinct that runs through Astro.