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

> Explore Astro deployment adapters like Node.js, Vercel, Cloudflare, and Netlify. Understand their key differences and use cases to choose the best fit for your project and deploy with confidence.

- Repository: [Astro/astro](https://github.com/withastro/astro)
- Tags: deep-dive
- Published: 2026-03-06

---

**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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/packages/integrations/node/src/index.ts), this adapter exports a `getAdapter` function that returns:

```typescript
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`](https://github.com/withastro/astro/blob/main/packages/integrations/vercel/src/index.ts), the `getAdapter` function supports both traditional serverless functions and edge middleware:

```typescript
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`](https://github.com/withastro/astro/blob/main/packages/integrations/netlify/src/index.ts) uses `setAdapter` to configure platform-specific features:

```typescript
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`](https://github.com/withastro/astro/blob/main/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`](https://github.com/withastro/astro/blob/main/packages/integrations/cloudflare/src/index.ts), the adapter configures unique features for the Workers environment:

```typescript
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`](https://github.com/withastro/astro/blob/main/astro.config.ts) after installing the package (`npm install -D @astrojs/node|vercel|netlify|cloudflare`).

### Node.js Configuration

```typescript
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

```typescript
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

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

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

```

### Cloudflare with KV and Images

```typescript
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.