Documentation Index Fetch the complete documentation index at: https://mintlify.com/withastro/astro/llms.txt
Use this file to discover all available pages before exploring further.
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 Or manually:
npm install @astrojs/node
Configuration 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:
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:
export default defineConfig ({ output: 'server' , adapter: node ({ mode: 'middleware' , }) , }) ;
Use with your own server:
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 Configuration 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:
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:
import { defineConfig } from 'astro/config' ; import vercel from '@astrojs/vercel/serverless' ; export default defineConfig ({ output: 'server' , adapter: vercel ({ imageService: true , }) , }) ;
Incremental Static Regeneration (ISR) 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 Configuration 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:
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:
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 Configuration 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:
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:
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 Configuration 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:
export default defineConfig ({ output: 'server' , adapter: node () , }) ;
Hybrid Mode Pages are static by default, opt-in to SSR:
export default defineConfig ({ output: 'hybrid' , adapter: vercel () , }) ;
Opt-in to SSR per page:
--- export const prerender = false ; ---
Static Mode All pages pre-rendered (no adapter needed):
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