Deploy to Cloudflare, Netlify, and Vercel

Purpose and Scope

This page explains how Astro’s hosted deployment story fits together for the three deployment families most readers ask about first: Cloudflare, Netlify, and Vercel. Astro projects are static by default, so a plain site can usually be built with astro build and uploaded as generated assets. When a project needs on-demand rendering, server routes, middleware, sessions, or other request-time behavior, the deployment target becomes adapter-driven. The adapter is the bridge between Astro’s build output and the platform’s functions, edge runtime, routing rules, asset handling, and platform-specific headers.

Cloudflare, Netlify, and Vercel all support static Astro sites, but their server-rendered paths differ. The official Cloudflare guide frames deployment around Cloudflare Workers and Wrangler, with @astrojs/cloudflare used when on-demand rendering is needed. The Netlify guide separates static, server-rendered, and edge-rendered modes, and recommends npx astro add netlify for on-demand rendering. The Vercel guide describes static and server-rendered deployment, with npx astro add vercel installing the adapter and updating astro.config.mjs. In all three cases, the first decision is whether the site is only static or needs request-time execution.

Relevant Source Files

• packages/integrations/vercel/src/index.ts - Main Vercel integration entry point, adapter feature declaration, routing constants, middleware headers, Node version support, and adapter configuration surface.
• packages/integrations/vercel/src/image/build-service.ts - Vercel image build service that maps Astro image options to Vercel image URLs, HTML attributes, and valid responsive widths.
• packages/integrations/vercel/src/cache/index.ts - Public cache helper for selecting the Vercel CDN cache provider for Astro route caching.
• packages/integrations/vercel/tsconfig.build.json - Build-time TypeScript project configuration for the Vercel integration package and its references to Astro and internal helpers.
• .github/workflows/examples-deploy.yml - Repository CI signal showing example-site changes triggering a Netlify build hook for preview.astro.new.
• .github/workflows/build-sandbox-image.yml - Repository CI signal for building a GHCR sandbox image, useful context for the project’s deployment-adjacent automation rather than an Astro hosting adapter.

Deployment Family Model

For Cloudflare, the operational unit is Workers plus static assets. A static site can be deployed with Wrangler by pointing the assets directory at ./dist; an on-demand rendered site uses the Cloudflare adapter and a Worker entry such as the generated worker output. The official docs sequence is intentionally practical: install Wrangler, add the adapter only when request-time rendering is required, ensure a Wrangler config exists, run npx astro build && npx wrangler dev for local preview, and deploy with Wrangler. That flow makes Cloudflare a good fit when the platform runtime and edge execution model are part of the application design.

Netlify’s model is broader from the user’s point of view: the same Astro project may be deployed as a static site, server-rendered site, or edge-rendered site. A static Astro site requires no adapter-specific configuration, while on-demand rendering is enabled with the Netlify adapter. The repository also contains a production-maintenance signal for Netlify: when files under examples/** change on main, a GitHub Actions workflow sends a POST request to a Netlify build hook to rebuild preview.astro.new. That does not define the Netlify adapter contract, but it shows Astro using Netlify as an official preview surface for example projects. Sources: .github/workflows/examples-deploy.yml

Vercel has the strongest implementation evidence in this source set. The integration declares itself as @astrojs/vercel, resolves its server entrypoint automatically, and advertises stable support for hybrid output, static output, server output, the Sharp image service, and environment secret access, with experimental support for i18n domains. It also models middleware mode, static headers, skew protection, and build output as adapter features. This means Vercel deployment is not just an upload target; it participates in routing, function generation, image behavior, cache behavior, and client-side asset URL decisions. Sources: packages/integrations/vercel/src/index.ts

Vercel Adapter Implementation Details

The Vercel adapter’s main entry point defines constants that explain the request path architecture used for server-rendered deployments. ASTRO_PATH_HEADER and ASTRO_PATH_PARAM carry the original path to the rendering function, while ASTRO_LOCALS_HEADER and ASTRO_MIDDLEWARE_SECRET_HEADER support middleware and locals handoff. The adapter reserves _render for the Node server path and _middleware for middleware-related output, and it has a special ISR path expression for routes whose original path must be recovered from the routing match. These details matter when diagnosing platform routing, middleware ordering, or unexpected paths in Vercel logs. Sources: packages/integrations/vercel/src/index.ts

The adapter also contains platform compatibility decisions that a project author rarely sees directly. It tracks supported Vercel Node versions, marking Node 24 as the default and Node 20 and 22 as available while Node 18 is deprecated. The adapter can enable skew protection by reading VERCEL_DEPLOYMENT_ID; when present, it sends an internal fetch header and appends an asset query parameter so client assets can be associated with a specific deployment. This is a deployment correctness feature: it reduces the chance that a page and its assets are resolved from different platform revisions during rollout. Sources: packages/integrations/vercel/src/index.ts

Images and Route Caching on Vercel

Astro’s image service contract is adapted to Vercel by packages/integrations/vercel/src/image/build-service.ts. The service extends Astro’s base service, validates options with Vercel production configuration, preserves SVG imports by returning their original source path, and sends other image requests through /_vercel/image with url, w, and q query parameters. It also computes missing dimensions for ESM-imported images from the source image aspect ratio and defaults rendered images to lazy loading and async decoding. Those defaults help generated HTML remain complete even when the platform image optimizer performs the actual transformation. Sources: packages/integrations/vercel/src/image/build-service.ts

Responsive image generation has an additional Vercel-specific constraint: getSrcSet() only returns widths that are valid for the configured Vercel image sizes. Instead of letting arbitrary requested widths flow through, the service reads the Vercel image configuration, sorts configured sizes, and builds the transform set from that platform-aware list. Route caching has a similarly small but explicit public surface. cacheVercel() returns a CacheProviderConfig named vercel with the entrypoint @astrojs/vercel/cache/provider, and its documentation comments identify Vercel-CDN-Cache-Control, Vercel-Cache-Tag, and tag invalidation via @vercel/functions as the intended platform mechanism. Sources: packages/integrations/vercel/src/image/build-service.ts, packages/integrations/vercel/src/cache/index.ts

Practical Deployment Flow

Use the same mental checklist for all three platforms. First, build the site locally and decide whether the output is static-only or requires on-demand rendering. Second, add the platform adapter only when request-time behavior is needed: npx astro add cloudflare, npx astro add netlify, or npx astro add vercel. Third, commit the generated configuration changes, because these adapters normally update astro.config.mjs and may create platform files such as Wrangler configuration. Fourth, use the host’s preview path before production: Wrangler local development for Cloudflare, Netlify UI or CLI previews for Netlify, and Vercel preview deployments for branch pushes.

# Static or adapter-backed production build
npx astro build
 
# Cloudflare local preview after configuring Wrangler
npx wrangler dev
 
# Adapter installation shortcuts when on-demand rendering is required
npx astro add cloudflare
npx astro add netlify
npx astro add vercel

For repository contributors, deployment confidence is also tied to CI automation. The Vercel package has its own build TypeScript configuration that includes ./src and ./virtual.d.ts, and references the Astro package plus internal helpers. That indicates the adapter is compiled as a workspace package rather than treated as an external script. Separately, the sandbox image workflow builds and pushes a GHCR image when sandbox files or the workflow change, using Buildx caching and pinned GitHub Actions. This workflow is not a hosting adapter, but it is a deployment-adjacent signal for reproducible project infrastructure. Sources: packages/integrations/vercel/tsconfig.build.json, .github/workflows/build-sandbox-image.yml

Compact Reference

Next Steps

If you are deploying an application, start from the platform guide that matches your host, then return to the adapter reference when behavior depends on server output, middleware, images, or cache invalidation. For Vercel-specific debugging, inspect whether the issue is route mapping, middleware handoff, image URL generation, or cache provider selection, because those concerns are implemented in separate Vercel integration modules. For broader deployment planning, read the deployment overview before choosing between static output, server output, hybrid output, and a platform adapter.