Deployment Overview

Purpose and Scope

Astro deployment starts with a simple split: a project can publish static files, or it can run a server-rendered application that produces responses on demand. The official deployment guides describe static output as the default path for Astro projects, where a build creates a dist/ directory that can be uploaded to a static host. Server-rendered deployment adds a runtime target, usually through an adapter, so requests can be handled by Node.js, an edge platform, or another host-specific runtime instead of only by prebuilt HTML files.

The source files for this page show the runtime side of that decision. Static sites still use Astro’s compiler and render pipeline during build, but their final deployment artifact is file-oriented. Server-rendered sites keep important rendering functions available at request time: pages, components, slots, head content, scripts, streaming, and framework island instructions are assembled by the server runtime exports. Reading these modules helps explain why deployment is not only a hosting choice; it determines when Astro executes rendering work and which runtime must be able to run it. Sources: packages/astro/src/runtime/server/render/index.ts, packages/astro/src/runtime/server/render/astro/index.ts, packages/astro/src/core/render/index.ts

Relevant Source Files

• packages/astro/src/runtime/server/render/component.ts — Implements server rendering for Astro and framework components, including hydration metadata, renderer selection, slots, and component-to-string behavior that matters when output is produced during build or at request time.
• packages/astro/src/core/render/index.ts — Re-exports core render pipeline building blocks such as Pipeline, getParams, getProps, loadRenderer, and Slots, tying route data and renderer loading to the deployable application model.
• packages/astro/src/runtime/server/render/astro/index.ts — Exposes Astro-component primitives such as AstroComponentFactory, component instances, renderTemplate, renderToString, and renderToReadableStream.
• packages/astro/src/runtime/server/render/index.ts — Collects the server render public surface used internally by Astro’s runtime, including page rendering, component rendering, head rendering, scripts, slots, streaming, and utility helpers.
• .github/workflows/build-sandbox-image.yml — Builds and publishes a GitHub Container Registry sandbox image from .flue/sandbox/Dockerfile, showing a containerized infrastructure deployment signal maintained by the repository.
• .github/workflows/examples-deploy.yml — Redeploys preview.astro.new through a Netlify build hook when examples change, showing how example projects are continuously published for preview use.

Deployment Modes

A static deployment is the easiest model to reason about. Astro evaluates routes, components, content, and integrations during build, then writes assets and HTML that any static file host can serve. The official docs’ Hostinger guide reflects this mode by instructing users to run a build and upload the contents of dist/ to a public web directory. In this mode, the deployed server does not need to know how to render an Astro component. It only serves files that Astro already produced, which makes static deployment portable across traditional hosting, object storage, CDN-backed platforms, and static site services.

A server-rendered deployment moves some of that work from build time to request time. The deployable application needs a runtime entrypoint and an adapter that knows the host platform’s request and response conventions. The selected server runtime exports show the pieces an adapter-backed app depends on: renderPage for full page responses, renderComponent and renderComponentToString for component output, renderStreaming for streamed responses, renderHead and maybeRenderHead for document head coordination, and slot/script helpers for preserving Astro semantics in rendered HTML. Sources: packages/astro/src/runtime/server/render/index.ts

Hybrid projects sit between these two ideas. Some routes can be prerendered into files, while others remain dynamic and require a server runtime. The official astro:static-paths reference describes how adapters can collect paths that need prerendering from within their target runtime, which is especially useful when a custom prerenderer runs outside Node. Conceptually, this means an adapter may participate in both halves of deployment: collecting static paths for build artifacts and preserving a request handler for routes that are rendered later.

System-to-Code Mapping

The core rendering exports are a useful map for understanding what must exist before an Astro app can be deployed. Pipeline represents the coordinated rendering environment, while getParams and getProps connect route matching with the data passed into pages. loadRenderer is the bridge between Astro and UI framework renderers, and Slots models child content passed into components. These are not hosting-provider APIs; they are framework internals that make static and server rendering behave consistently regardless of where the final output is hosted. Sources: packages/astro/src/core/render/index.ts

Deployment concern	Runtime surface	Why it matters
Route rendering	renderPage	Produces full page responses for server-rendered routes.
Component output	renderComponent, renderComponentToString	Converts Astro and framework components into HTML or render instances.
Astro template execution	renderTemplate, renderToString, renderToReadableStream	Supports string and stream-oriented rendering paths.
Head and asset coordination	maybeRenderHead, renderHead, renderScript, renderUniqueStylesheet	Preserves document head, script, and stylesheet behavior across deployment targets.
Slots and fragments	renderSlot, renderSlotToString, Fragment	Keeps component composition stable when rendered during build or request handling.

The component renderer is where deployment mode becomes visible at the component boundary. renderFrameworkComponent inspects hydration directives, records metadata such as the directive name and component URL, renders slots, and asks registered renderers whether they can handle a component. It also contains renderer guessing for common framework file types and recognizes client-only values for Solid, React, Preact, Vue, and Svelte. A static build can perform this work once and emit the result; server-rendered deployment must keep the necessary renderer and hydration machinery available in the runtime bundle. Sources: packages/astro/src/runtime/server/render/component.ts

Execution Flow

For a static host, the practical flow is: build the project, verify the generated output, and publish the resulting files. The rendering pipeline still resolves route params, props, component trees, head content, scripts, and framework island instructions, but that work is completed before upload. The deployment target only needs to serve the generated files and assets. This is why static deployment is the default recommendation for sites whose pages do not require per-request data, session-aware responses, or server-only side effects.

For a server-rendered host, the practical flow is: configure the proper adapter, build the project for that runtime, deploy the server output, and route incoming requests to the adapter’s handler. At request time, the handler invokes Astro’s app and render machinery to produce a Response. The runtime render exports show why this server bundle must include more than a single HTML function: it may need component rendering, readable streams, unique stylesheet emission, script rendering, and HTML element rendering, depending on the page being requested. Sources: packages/astro/src/runtime/server/render/index.ts, packages/astro/src/runtime/server/render/astro/index.ts

When choosing between these modes, start from the behavior your routes require. Marketing pages, documentation, blogs, and content pages often fit static output because their data is known at build time. Dashboards, authenticated areas, webhooks, form handlers, and personalized pages usually require server rendering or endpoint support. If only some routes are dynamic, prefer prerendering the rest so the deployment keeps Astro’s lightweight output promise while reserving runtime work for the routes that actually need it.

CI/CD and Hosting Signals

The repository includes a workflow that redeploys preview.astro.new when example projects change. It runs on pushes to main that touch examples/**, checks out the repository, and sends a POST request to a Netlify build hook stored in repository secrets. This is a useful signal for Astro users because examples are not treated as inert documentation; they are continuously pushed through a hosted preview pipeline so changes can be validated in a deployment-like environment. Sources: .github/workflows/examples-deploy.yml

A second workflow builds a sandbox container image and publishes it to GitHub Container Registry. It is triggered by changes to the sandbox Dockerfile, sandbox agent instructions, or the workflow itself, and it uses Docker Buildx with GitHub Actions cache support. Although this workflow is not an Astro site deployment recipe, it shows the repository’s broader deployment discipline: runtime environments are versioned, built from source-controlled inputs, pushed with stable and content-addressed tags, and protected by scoped workflow permissions. Sources: .github/workflows/build-sandbox-image.yml

Choosing the Next Page

If you are deploying a static site, continue with the hosting guide that matches your platform and keep the deployment artifact centered on the build output directory. If you need runtime rendering, read the adapter-specific deployment pages before changing hosting providers, because each adapter defines how Astro’s server output is packaged and invoked. For deeper internals, move from this overview to server-side rendering, on-demand rendering, image service behavior, or the adapter deployment pages. Those pages explain the runtime contracts in more detail while this page gives the shared mental model: static deployment serves completed files, and server-rendered deployment keeps Astro’s render pipeline alive behind a platform adapter.