Build pipeline

astro build is implemented by AstroBuilder (packages/astro/src/core/build/), which runs a Vite SSR build, then walks the route manifest and emits HTML for every static page, then hands off to the configured adapter.

Purpose

Produce a deployable artifact: either a dist/ folder of static HTML (default), a dist/server/ with an adapter entrypoint (SSR), or a hybrid mix.

Key files

File	Purpose
packages/astro/src/cli/build/index.ts	CLI entry.
packages/astro/src/core/build/index.ts	AstroBuilder class — orchestrator.
packages/astro/src/core/build/static-build.ts	Walks routes, prerenders pages, the largest single file in core/build/ (670 lines).
packages/astro/src/core/build/pipeline.ts	BuildPipeline — the build-time Pipeline.
packages/astro/src/core/build/generate.ts	Drives the per-page render loop.
packages/astro/src/core/build/page-data.ts	Loads compiled page modules + their dependencies.
packages/astro/src/core/build/plugins/	Internal Vite plugins specific to the build (CSS chunking, asset paths, manifest emission).
packages/astro/src/core/build/default-prerenderer.ts	The default per-page prerender invocation.
packages/astro/src/core/app/manifest.ts	Builds the SSRManifest injected into adapter entrypoints.

High-level flow

graph TD
    A[CLI: astro build] --> B[AstroBuilder.run]
    B --> C[astro:build:start hook]
    C --> D[Vite SSR build]
    D --> E[Collect emitted modules + CSS map]
    E --> F[Walk route manifest]
    F --> G{Route is prerendered?}
    G -- yes --> H[BuildPipeline + RenderContext → write HTML]
    G -- no --> I[Skip; route handled at runtime]
    H --> J[Server islands and 404 page]
    I --> K[Emit adapter entrypoint]
    K --> L[astro:build:done hook]
    L --> M[Final dist/]

Static + SSR coexistence

A single astro build produces a unified output where:

• Static routes live in dist/ (or outDir).
• SSR routes live alongside an adapter-emitted entrypoint (e.g. dist/server/entry.mjs).
• The adapter receives the route manifest and decides how to fan out (per-route Lambdas on Vercel, a single Worker on Cloudflare, etc.).

packages/astro/src/core/build/static-build.ts toggles between modes by inspecting each route's prerender flag. The flag is computed in packages/astro/src/core/routing/prerender.ts from per-page export const prerender and the project-wide output config.

Server islands at build time

packages/astro/src/core/server-islands/ registers a Vite plugin that:

1. Replaces <Component server:defer /> with a placeholder.
2. Emits an _server-islands/<id>.js endpoint at build time.
3. Generates a runtime fetch that the placeholder uses on the client.

The result is that the static page ships with all-but-the-island prerendered, and the island fetches lazily.

Build hooks

• astro:build:start — fires before the Vite build. Used by integrations to mutate config or print banners.
• astro:build:setup — receives the Vite config that's about to be used.
• astro:build:ssr — fires once per SSR build, gives integrations a chance to instrument it.
• astro:build:generated — fires after every page is generated.
• astro:build:done — fires after the final write. Most adapters and @astrojs/sitemap consume this hook.

The hook payloads are typed in packages/astro/src/types/public/integrations.ts.

Build-time logging

The build prints a tree of routes and their sizes, color-coded by output mode (static vs server). Source: packages/astro/src/core/messages/.

Entry points for modification

• Change how a route emits HTML: core/build/generate.ts and default-prerenderer.ts.
• Add an internal build plugin: core/build/plugins/. New plugins should declare their position in the plugin list in static-build.ts.
• Mutate the manifest format: core/app/manifest.ts and core/app/types.ts (the SSRManifest shape is shared with adapters and the runtime).

Related pages

• systems / routing
• systems / render context
• packages / integrations / adapters — what consumes the build output.
• features / server islands