SSR Adapters

Deploy Astro with server-side rendering using Node, Vercel, Netlify, Cloudflare, and Deno adapters

SSR adapters allow you to deploy your Astro site with server-side rendering (SSR) to various hosting platforms. Each adapter configures your output to match the requirements of a specific deployment target.

When to Use Adapters

You need an adapter when:

• Using output: 'server' or output: 'hybrid' mode
• Implementing on-demand rendering for dynamic routes
• Using server endpoints and API routes
• Deploying to a platform that requires a specific output format

For static sites (output: 'static'), you don’t need an adapter.

Available Adapters

Node

Deploy to any Node.js host

Vercel

Deploy to Vercel with serverless or edge functions

Netlify

Deploy to Netlify with serverless functions

Cloudflare

Deploy to Cloudflare Pages or Workers

Deno

Deploy to Deno Deploy

Node

The Node adapter allows you to deploy your SSR site to any Node.js environment.

Installation

npx astro add node

Or manually:

npm install @astrojs/node

Configuration

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

Options

node({
  // Mode: 'middleware' or 'standalone'
  mode: 'standalone',
})

Standalone Mode

Creates a server that starts when the entry module is run:

astro.config.mjs

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

Start the server:

node ./dist/server/entry.mjs

Middleware Mode

Exports the handler for use with your own HTTP server:

astro.config.mjs

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'middleware',
  }),
});

Use with your own server:

server.mjs

import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();

// Serve static files
app.use(express.static('dist/client/'));

// Use the Astro handler
app.use(ssrHandler);

app.listen(8080);

Deployment

Build your project and start the server:

npm run build
node ./dist/server/entry.mjs

Or with a custom port:

HOST=0.0.0.0 PORT=3000 node ./dist/server/entry.mjs

Vercel

The Vercel adapter deploys your site to Vercel with serverless or edge functions.

Installation

npx astro add vercel

Configuration

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Options

vercel({
  // Enable Web Analytics
  webAnalytics: {
    enabled: true,
  },
  
  // Enable Speed Insights
  speedInsights: {
    enabled: true,
  },
  
  // Enable Image Optimization
  imageService: true,
  
  // ISR configuration
  isr: {
    expiration: 60,
    exclude: ['/api/*'],
  },
  
  // Include files in deployment
  includeFiles: ['./data/config.json'],
  
  // Maximum duration for serverless functions (seconds)
  maxDuration: 30,
})

Edge Functions

Use Vercel Edge Functions instead of serverless:

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: vercel(),
});

Per-Route Configuration

Set configuration per route using route export:

src/pages/api/cached.astro

---
export const prerender = false;
export const config = {
  runtime: 'edge',
};

export async function GET() {
  return new Response('Hello from edge!');
}
---

Image Optimization

Enable Vercel’s Image Optimization:

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: vercel({
    imageService: true,
  }),
});

Incremental Static Regeneration (ISR)

astro.config.mjs

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

export default defineConfig({
  output: 'hybrid',
  adapter: vercel({
    isr: {
      // Cache pages for 60 seconds
      expiration: 60,
    },
  }),
});

Netlify

The Netlify adapter deploys your site to Netlify with serverless functions.

Installation

npx astro add netlify

Configuration

astro.config.mjs

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

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

Options

netlify({
  // Use Edge Functions
  edgeMiddleware: false,
  
  // Cache on-demand rendered pages
  cacheOnDemandPages: true,
  
  // Builders for DPR (Distributed Persistent Rendering)
  builders: false,
})

Edge Functions

Use Netlify Edge Functions:

astro.config.mjs

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

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

Distributed Persistent Rendering (DPR)

Cache rendered pages at the edge:

astro.config.mjs

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

export default defineConfig({
  output: 'hybrid',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

Set cache headers per page:

src/pages/products/[id].astro

---
export const prerender = false;

Astro.response.headers.set(
  'CDN-Cache-Control',
  'public, max-age=3600, s-maxage=3600'
);
---

Image CDN

Netlify automatically optimizes images:

---
import { Image } from 'astro:assets';
import myImage from '../assets/my-image.png';
---

<Image src={myImage} alt="My image" />

Cloudflare

The Cloudflare adapter deploys your site to Cloudflare Pages or Workers.

Installation

npx astro add cloudflare

Configuration

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Options

cloudflare({
  // Mode: 'directory' (default) or 'advanced'
  mode: 'directory',
  
  // Routes configuration
  routes: {
    // Extend routes.json
    extend: {
      include: ['/custom-route'],
      exclude: ['/api/*'],
    },
  },
  
  // Image service
  imageService: 'cloudflare',
})

Access Runtime APIs

Access Cloudflare runtime in your pages:

src/pages/api/data.json.ts

export async function GET({ locals }) {
  const { runtime } = locals;
  
  // Access KV namespace
  const value = await runtime.env.MY_KV.get('key');
  
  // Access D1 database
  const result = await runtime.env.DB.prepare(
    'SELECT * FROM users WHERE id = ?'
  ).bind(1).all();
  
  return new Response(JSON.stringify({ value, result }));
}

Wrangler Configuration

Configure Cloudflare resources in wrangler.toml:

wrangler.toml

name = "my-astro-app"
compatibility_date = "2024-03-15"

[[kv_namespaces]]
binding = "MY_KV"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Cloudflare Pages Functions

For advanced use cases, use directory mode:

astro.config.mjs

export default defineConfig({
  output: 'server',
  adapter: cloudflare({ mode: 'directory' }),
});

Add custom functions in functions/ directory.

Deno

The Deno adapter allows you to deploy to Deno Deploy.

Installation

npx astro add deno

Configuration

astro.config.mjs

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

export default defineConfig({
  output: 'server',
  adapter: deno(),
});

Deployment

Deploy using the Deno CLI:

deno deploy --project=my-project ./dist/server/entry.mjs

Or connect your GitHub repository to Deno Deploy for automatic deployments.

Choosing Output Mode

Adapters work with different output modes:

Server Mode

All pages rendered on-demand:

astro.config.mjs

export default defineConfig({
  output: 'server',
  adapter: node(),
});

Hybrid Mode

Pages are static by default, opt-in to SSR:

astro.config.mjs

export default defineConfig({
  output: 'hybrid',
  adapter: vercel(),
});

Opt-in to SSR per page:

src/pages/dynamic.astro

---
export const prerender = false;
---

Static Mode

All pages pre-rendered (no adapter needed):

astro.config.mjs

export default defineConfig({
  output: 'static',
  // No adapter needed
});

Next Steps

Server Endpoints

Create API endpoints with server-side logic

On-Demand Rendering

Learn about server-side rendering in Astro