This document provides a high-level overview of Astro's deployment adapter system—a modular framework that enables Astro projects to be deployed seamlessly across various hosting platforms. Deployment adapters transform Astro's build output into formats, configurations, and runtimes tailored for specific platforms like Vercel, Cloudflare, Netlify, and Node.js servers.
Each adapter is packaged as an integration that hooks into Astro's build process and runtime, abstracting platform-specific logic. This system underpins Astro's "build once, deploy anywhere" philosophy by allowing a consistent development experience while targeting diverse environments.
Officially supported adapters (each exporting an integration function) include:
@astrojs/vercel — packages/integrations/vercel/package.json2@astrojs/cloudflare — packages/integrations/cloudflare/package.json2@astrojs/netlify — packages/integrations/netlify/package.json2@astrojs/node — packages/integrations/node/package.json2For in-depth discussions and implementation details, refer to the child pages:
Sources: packages/integrations/vercel/package.json1-27 packages/integrations/cloudflare/package.json1-31 packages/integrations/netlify/package.json1-26 packages/integrations/node/package.json1-24
Adapters act as platform-specific transformers and configurators within Astro’s build pipeline. They convert Astro’s server build output and static assets into the deployment formats required by targeted platforms. Adapters also augment the build with platform integrations, middleware setup, runtime hooks, and generate supplemental files such as redirects and route manifests.
This abstraction allows developers to focus on building Astro sites without managing deployment complexities unique to each platform.
Sources: packages/integrations/vercel/CHANGELOG.md108-112 packages/integrations/netlify/CHANGELOG.md140-143 packages/integrations/node/CHANGELOG.md51-54
Adapters implement the AstroAdapter interface and integrate with Astro through lifecycle hooks. This interface defines adapter identity, supported features, runtime entry points, and adapter-specific options.
Adapter implementations hook into specific Astro lifecycle events to setup, validate, and transform builds:
| Hook | Purpose | Typical Adapter Usage | Common Actions |
|---|---|---|---|
astro:config:setup | Early configuration setup | Register adapter with setAdapter() | Inject Vite plugins, initialize adapter config |
astro:config:done | Finalize configuration | Validate user settings and adapter compatibility | Access config.output, check features |
astro:build:done | Post build processing | Transform default build outputs to platform-specific formats | Emit platform files, bundle serverless functions |
astro:server:setup | Setup dev server environment | Configure dev server with platform-specific integration | Add dev-only plugins (e.g., @cloudflare/vite-plugin) |
Sources: packages/astro/src/integrations/hooks.ts1-20 packages/astro/src/types/public/integrations.ts1-50 packages/astro/src/integrations/features-validation.ts1-30
Different platforms impose unique requirements and capabilities. The official adapters support a set of common and platform-specific capabilities as shown below:
| Feature | Vercel | Cloudflare | Netlify | Node.js |
|---|---|---|---|---|
| middlewareMode | edge | classic | edge | classic |
| staticHeaders | Supported | Not supported | Supported | Supported |
| Sessions Storage | Manual | KV Namespace provisioned | Blobs (@netlify/blobs) | File system or custom drivers |
| Image Service | Platform API | workerd runtime bindings | Image CDN | Sharp-based |
| ISR (Incremental Static Regeneration) | Supported | Not supported | Not supported | Not supported |
| Skew Protection | Supported | Not supported | Supported | Not supported |
'edge' mode to enable edge middleware execution. packages/integrations/vercel/CHANGELOG.md148 packages/integrations/netlify/CHANGELOG.md32-34@netlify/blobs package. packages/integrations/netlify/package.json45Sources: packages/integrations/vercel/CHANGELOG.md37-46 packages/integrations/netlify/CHANGELOG.md66-82 packages/integrations/node/CHANGELOG.md115-118 packages/integrations/cloudflare/CHANGELOG.md111-114
Adapters are configured in the user's project astro.config.mjs under the adapter property. They accept options that customize platform-specific behavior such as middleware mode, static headers, image services, and session configurations.
Sources: packages/integrations/vercel/CHANGELOG.md44-54 packages/integrations/netlify/CHANGELOG.md73-83 packages/integrations/node/CHANGELOG.md88
Astro generates a standardized server build, client assets, and SSR manifest. Each adapter transforms these artifacts into outputs that conform to the deployment platform's requirements.
Sources: packages/integrations/vercel/package.json19-27 packages/integrations/cloudflare/package.json19-35 packages/integrations/netlify/package.json19-28 packages/integrations/node/package.json19-24
Adapters enhance both local development and production deployments by providing platform-accurate environment setups.
workerd runtime in development via @cloudflare/vite-plugin for local Worker simulation. packages/integrations/cloudflare/package.json49dev-image-service to simulate image handling locally. packages/integrations/vercel/package.json24@netlify/vite-plugin to emulate Netlify Functions and features during astro dev. packages/integrations/netlify/package.json47Sources: packages/integrations/cloudflare/package.json41-51 packages/integrations/netlify/package.json32-49 packages/integrations/vercel/package.json23-24
Astro's deployment adapters form a modular bridge between universal build artifacts and diverse hosting ecosystems. They:
_redirects, _worker.js).For detailed technical information, see the child pages for Adapter System Architecture, Vercel Adapter, Cloudflare Adapter, Netlify Adapter, and Node.js Adapter.
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.