Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us