This document describes the adapter system architecture in Astro, explaining how adapters bridge Astro's unified build output to platform-specific deployment targets. Adapters implement a standardized interface that allows them to transform Astro's generic build artifacts into formats required by specific hosting platforms (Vercel, Cloudflare, Netlify, Node.js, etc.).
For information about individual adapter implementations, see Vercel Adapter, Cloudflare Adapter, Netlify Adapter, and Node.js Adapter. For details on how adapters integrate into Astro's extension system, see Integration System.
Adapters implement the AstroAdapter interface by calling setAdapter() in the astro:config:done hook packages/integrations/hooks.ts184-186 The adapter is a specialized Astro integration that declares deployment-specific capabilities via the adapterFeatures object packages/astro/src/core/config/schemas/base.ts141
| Property | Type | Purpose |
|---|---|---|
name | string | Package name (e.g., @astrojs/vercel) packages/astro/src/core/config/schemas/base.ts141 |
serverEntrypoint | string | Path to server handler module (e.g., astro/entrypoints/legacy) packages/astro/src/core/build/plugins/plugin-ssr.ts42 |
exports | string[] | Additional modules to bundle with server output packages/astro/src/core/build/plugins/plugin-ssr.ts108-118 |
adapterFeatures.buildOutput | 'static' | 'server' | Declares adapter's output type packages/astro/src/core/build/generate.ts46 |
adapterFeatures.middlewareMode | 'classic' | 'edge' | Middleware execution environment packages/astro/src/core/app/types.ts88-92 |
Sources: packages/astro/src/core/config/schemas/base.ts141 packages/astro/src/core/build/plugins/plugin-ssr.ts42-124 packages/astro/src/core/app/types.ts88-92
Adapters participate in Astro's build process through integration lifecycle hooks. These hooks allow adapters to modify configuration, inject assets, transform build output, and generate platform-specific deployment artifacts.
astro:config:setupCalled early in the build process. Adapters use the provided utilities to add Vite plugins and inject routes packages/integrations/hooks.ts176-204
astro:config:doneCalled after configuration is resolved. Receives { setAdapter, config }. This is where the adapter registers its features and capabilities packages/integrations/hooks.ts184-186
astro:build:ssrCalled during the SSR bundle generation. Receives the manifest and logger packages/astro/src/core/build/plugins/plugin-manifest.ts91-98 Prerendered routes' styles are often stripped from the SSR manifest here to keep the entry chunk small packages/astro/src/core/build/plugins/plugin-manifest.ts99-103
astro:build:doneCalled after build completion. Receives { dir, routes, pages }. The build system finalizes the static image list and asset generation env before this hook packages/astro/src/core/build/generate.ts7-11
Sources: packages/integrations/hooks.ts176-204 packages/astro/src/core/build/plugins/plugin-manifest.ts91-103 packages/astro/src/core/build/generate.ts7-11
Astro's build system produces a standardized output structure that adapters transform into platform-specific formats. The SSRManifest serves as the single source of truth for these transformations packages/astro/src/core/build/plugins/plugin-manifest.ts43-61
The serialized manifest (virtual:astro:manifest) is the central bridge. In production, plugin-manifest injects the real build-specific data (routes, assets, CSP hashes) at the end of the bundling process by replacing the @@ASTRO_MANIFEST_REPLACE@@ token packages/astro/src/core/build/plugins/plugin-manifest.ts63-68
Sources: packages/astro/src/core/build/plugins/plugin-manifest.ts43-80 packages/astro/src/core/app/types.ts63-148
Adapters declare their capabilities, which Astro core uses to validate user configuration and enable or disable features like Astro.clientAddress.
| Feature | Logic | Error if Unsupported |
|---|---|---|
Astro.clientAddress | Checked during SSR rendering | ClientAddressNotAvailable packages/astro/src/core/errors/errors-data.ts46-51 |
| Prerendering | Validated during page generation | PrerenderClientAddressNotAvailable packages/astro/src/core/errors/errors-data.ts60-65 |
| Middleware Mode | Resolved during manifest creation | resolveMiddlewareMode packages/astro/src/core/build/plugins/plugin-manifest.ts89 |
The system uses bit flags to track which features are active in the pipeline (e.g., redirects, sessions, actions, i18n) packages/astro/src/core/base-pipeline.ts39-46
Sources: packages/astro/src/core/base-pipeline.ts39-56 packages/astro/src/core/errors/errors-data.ts46-81
Astro provides several virtual modules to facilitate adapter integration:
virtual:astro:adapter-entrypoint: Exports the adapter's server entrypoint packages/astro/src/core/build/plugins/plugin-ssr.ts16-17virtual:astro:adapter-config: Exposes the adapter's specific arguments packages/astro/src/core/build/plugins/plugin-ssr.ts19-20virtual:astro:legacy-ssr-entry: Provides a bridge for older adapter entrypoint patterns packages/astro/src/core/build/plugins/plugin-ssr.ts13-14The generatePages function coordinates the static generation phase. It uses a DefaultPrerenderer to handle the actual rendering of static routes discovered during the build packages/astro/src/core/build/generate.ts40-86 It also handles route priority and conflict resolution (e.g., when multiple routes match the same path) packages/astro/src/core/build/generate.ts108-156
Adapters rely on shared utilities for common tasks:
collapseDuplicateSlashes, joinPaths, trimSlashes packages/astro/src/core/routing/rewrite.ts1-15FORBIDDEN_PATH_KEYS to protect sensitive runtime properties packages/astro/src/core/base-pipeline.ts30Sources: packages/astro/src/core/app/types.ts63-148 packages/astro/src/core/base-pipeline.ts64-120 packages/astro/src/core/build/plugins/plugin-ssr.ts136-151 packages/astro/src/core/build/generate.ts40-86 packages/astro/src/core/config/schemas/base.ts93-181
Sources:
packages/astro/src/core/app/types.ts:63-148packages/astro/src/core/base-pipeline.ts:39-120packages/astro/src/core/build/generate.ts:40-156packages/astro/src/core/build/plugins/plugin-manifest.ts:43-117packages/astro/src/core/build/plugins/plugin-ssr.ts:13-151packages/astro/src/core/config/schemas/base.ts:93-181packages/astro/src/core/errors/errors-data.ts:46-96packages/astro/src/core/routing/rewrite.ts:1-134packages/integrations/hooks.ts:176-204Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.