Astro Deployment Adapters: How to Choose Between Node.js, Vercel, Cloudflare, and Netlify

Astro deployment adapters translate static and server-rendered builds into platform-specific outputs, with Node.js offering universal compatibility, Vercel providing edge middleware and skew protection, Netlify generating serverless functions and redirects, and Cloudflare enabling Workers-based edge computing with KV storage.

Astro's first-party adapters enable server-side rendering (SSR) across diverse infrastructure targets by implementing the AstroAdapter interface defined in the withastro/astro repository. Each adapter exposes specific adapterFeatures—including buildOutput, middlewareMode, and staticHeaders—that configure the build pipeline to emit compatible artifacts for your chosen hosting platform.

What Are Astro Deployment Adapters?

Astro deployment adapters are integration packages that export a configuration object conforming to the AstroAdapter type. According to the source code in packages/astro/src/types/public/integrations.ts, each adapter must return an object specifying:

• adapterFeatures: An object declaring buildOutput (either 'server' or 'static'), middlewareMode ('classic' or 'edge'), and optional staticHeaders support.
• serverEntrypoint: The path to the runtime server code that handles incoming requests.
• Platform-specific options: Additional parameters for CDN features, storage bindings, or deployment protections.

When you run astro build, the core framework reads these features to determine whether to emit a standalone Node.js server, serverless functions, or edge worker bundles.

Node.js Adapter: Universal Server Deployment

The Node.js adapter provides the most flexible deployment option for environments you control. Located at packages/integrations/node/src/index.ts, this adapter exports a getAdapter function that returns:

export function getAdapter({ staticHeaders }: Pick<Options, 'staticHeaders'>): AstroAdapter {
  return {
    name: '@astrojs/node',
    entrypointResolution: 'auto',
    serverEntrypoint: '@astrojs/node/server.js',
    previewEntrypoint: '@astrojs/node/preview.js',
    adapterFeatures: {
      buildOutput: 'server',
      middlewareMode: 'classic',
      staticHeaders,
    },
  };
}

Key characteristics:

• buildOutput: 'server': Generates a full SSR server compatible with http.createServer.
• middlewareMode: 'classic': Enables use as Express-style middleware via (req, res, next) signatures.
• staticHeaders: When enabled, writes Content Security Policy headers to a JSON file for runtime injection.

Use this adapter when deploying to Docker containers, Virtual Private Servers (VPS), Railway, Fly.io, or as middleware within existing Express/Koa applications.

Vercel Adapter: Serverless and Edge Functions

The Vercel adapter optimizes output for Vercel's serverless and edge runtimes. In packages/integrations/vercel/src/index.ts, the getAdapter function supports both traditional serverless functions and edge middleware:

function getAdapter({
  middlewareMode,
  skewProtection,
  buildOutput,
  staticHeaders,
}): AstroAdapter {
  return {
    name: '@astrojs/vercel',
    entrypointResolution: 'auto',
    serverEntrypoint: `${PACKAGE_NAME}/entrypoint`,
    adapterFeatures: {
      buildOutput,
      middlewareMode,
      staticHeaders,
    },
    client: {
      internalFetchHeaders: skewProtection ? () => {
        const deploymentId = process.env.VERCEL_DEPLOYMENT_ID;
        return deploymentId ? { 'x-deployment-id': deploymentId } : {};
      } : undefined,
    },
  };
}

Key characteristics:

• middlewareMode: 'edge': Deploys Astro middleware as a Vercel Edge Function instead of a serverless function.
• skewProtection: Adds x-deployment-id headers to prevent CDN race conditions during rollouts.
• Build Output API: Automatically generates the .vercel/output directory structure with optimized route configurations.

Use this adapter when leveraging Vercel's automatic CDN, preview deployments, or when you need edge-level execution for authentication and geolocation headers.

Netlify Adapter: Functions and Redirects

The Netlify adapter generates output compatible with Netlify Functions and edge handlers. The implementation in packages/integrations/netlify/src/index.ts uses setAdapter to configure platform-specific features:

setAdapter({
  name: '@astrojs/netlify',
  adapterFeatures: {
    buildOutput: 'server',
    middlewareMode: 'classic',
    staticHeaders,
  },
});

Key characteristics:

• Generates Netlify Functions bundles in .netlify/functions for SSR routes.
• Writes _redirects and netlify/v1/config.json files for handling redirects, custom cache headers, and remote image patterns.
• Supports staticHeaders for injecting security headers into static assets.

Use this adapter when deploying to Netlify's infrastructure, particularly if you require their built-in redirect rules, split testing capabilities, or Git-integrated CI/CD workflows.

Cloudflare Adapter: Workers and Edge Storage

The Cloudflare adapter targets Cloudflare Workers and Workers Sites, offering edge-native performance and storage integration. In packages/integrations/cloudflare/src/index.ts, the adapter configures unique features for the Workers environment:

setAdapter({
  name: '@astrojs/cloudflare',
  adapterFeatures: {
    buildOutput: 'server',
    middlewareMode: 'classic',
    preserveBuildClientDir: true,
  },
});

Key characteristics:

• preserveBuildClientDir: true: Maintains the client assets directory alongside the worker bundle, which is required for Workers Sites.
• KV Bindings: Supports sessionKVBindingName to attach Cloudflare KV namespaces for session storage.
• Image Transformations: Enables imageService: 'cloudflare-binding' to process images via Cloudflare Images.
• Environment Shimming: Provides a shimmed process.env object for compatibility with Node.js libraries expecting traditional environment variable access.

Use this adapter when building globally distributed applications requiring ultra-low latency, KV-backed state management, or integration with Cloudflare's edge network.

Adapter Configuration Examples

Configure your chosen adapter in astro.config.ts after installing the package (npm install -D @astrojs/node|vercel|netlify|cloudflare).

Node.js Configuration

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ 
    mode: 'standalone', // or 'middleware'
    staticHeaders: true 
  }),
});

Vercel with Edge Middleware

import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
  output: 'server',
  adapter: vercel({
    middlewareMode: 'edge',
    skewProtection: true,
    staticHeaders: true,
  }),
});

Netlify Configuration

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',
  adapter: netlify({ staticHeaders: true }),
});

Cloudflare with KV and Images

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    staticHeaders: true,
    imageService: 'cloudflare-binding',
    sessionKVBindingName: 'SESSIONS',
  }),
});

Summary

• Node.js: Universal compatibility for Docker, VPS, and custom servers with classic middleware support.
• Vercel: Optimized for serverless and edge deployments with skew protection and automatic output formatting.
• Netlify: Generates Functions-compatible bundles with automatic redirect and configuration file generation.
• Cloudflare: Workers-native runtime with KV storage bindings, image transformation, and client directory preservation.
• Static Headers: All four adapters support the staticHeaders option for injecting CSP headers into static assets.
• Middleware Modes: Node, Netlify, and Cloudflare default to 'classic' mode, while Vercel uniquely supports 'edge' middleware deployment.

Frequently Asked Questions

Which Astro adapter should I use for Docker deployments?

Use the Node.js adapter. It emits a standalone server bundle that runs in any Node.js environment without platform-specific dependencies, making it ideal for containerized deployments on Docker, Railway, or Fly.io.

Can I deploy Astro middleware to the edge with Vercel?

Yes. The Vercel adapter supports middlewareMode: 'edge', which deploys your Astro middleware as a Vercel Edge Function rather than a serverless function. This enables access to geolocation data and authorization checks at the CDN level before hitting your origin.

How do I enable Content Security Policy headers in Astro adapters?

Set staticHeaders: true in your adapter configuration. This option—available in the Node.js, Vercel, Netlify, and Cloudflare adapters—writes CSP headers to a JSON manifest that the platform's runtime injects into HTTP responses for static assets.

What is the difference between classic and edge middleware mode in Astro?

Classic middleware (middlewareMode: 'classic') runs within the standard server runtime (Node.js process, serverless function, or worker) after the request reaches your origin. Edge middleware (middlewareMode: 'edge'), supported exclusively by the Vercel adapter, executes at the CDN edge before the request reaches your serverless functions, offering lower latency for redirects, A/B testing, and authentication checks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}