astro build: Static and SSR Astro Builds
astro build compiles an Astro project into dist/, producing static HTML or a server bundle depending on the configured adapter.
Astro ships mostly static output by default. In CI you build, and separately run astro check as the type gate since the build itself does not fail on all type issues.
What it does
astro build renders pages and writes optimized output to dist/. With no adapter it emits a static site; with an SSR adapter it emits a server entry plus assets. astro check runs the TypeScript/diagnostic pass over .astro files.
Common usage
astro build
# typecheck gate, then build
astro check && astro build
# preview the built site
astro previewOptions
| Command / Flag | What it does |
|---|---|
| astro build | Build the site into dist/ |
| astro check | Run type and diagnostic checks |
| astro preview | Serve the built output locally |
| --config <file> | Use a specific astro.config file |
| --verbose | Verbose logging |
In CI
Run astro check as its own step so type errors fail the pipeline; a plain astro build will not catch every type issue. Pick the adapter that matches your host, and confirm output mode (static vs server) is what the deploy expects.
Common errors in CI
"[ERROR] Could not resolve \"X\"" during build means a missing dependency or import path. "astro check" reports errors as "Error: ..." with counts like "N errors, M warnings" and exits non-zero. A "Cannot use import.meta" or adapter error means the output mode and adapter do not match (static build using server-only features).