Deployment Guide

Learn how to deploy your Astro site to production with static hosting or SSR adapters

Overview

Astro supports multiple deployment strategies depending on your project needs. You can deploy as a static site or enable server-side rendering (SSR) with adapters for various hosting platforms.

1. Build Your Site

   Run the build command to create a production-ready version of your site:

   astro build
   

   By default, this creates a dist/ directory with your built site.

2. Choose Your Deployment Strategy

   Astro supports two main deployment modes:

   • Static (SSG): Pre-renders all pages at build time
   • Server (SSR): Renders pages on-demand with an adapter
3. Deploy

   Upload your dist/ folder to your hosting provider or configure your adapter for automatic deployment.

Static Site Deployment

For static sites, Astro builds all pages to HTML at build time. This is the default mode and works with any static hosting provider.

Configuration

astro.config.mjs

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

export default defineConfig({
  site: 'https://example.com',
  integrations: [sitemap()],
});

Popular Static Hosting Providers

Netlify

Drop-in support with zero configuration. Just connect your Git repository.

Vercel

Automatic deployments from Git with preview URLs for every commit.

Cloudflare Pages

Fast global CDN with unlimited bandwidth on the free tier.

GitHub Pages

Free hosting for public repositories with custom domain support.

Server-Side Rendering (SSR)

For dynamic features like API routes, user authentication, or database queries, use SSR with an adapter.

Node.js Adapter

The Node adapter allows you to deploy to any platform that supports Node.js:

astro.config.mjs

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

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

Deployment Example:

# Install dependencies
npm install

# Build the site
npm run build

# Run in production
node ./dist/server/entry.mjs

Vercel Adapter

Deploy serverless functions to Vercel’s edge network:

astro.config.mjs

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

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

Netlify Adapter

Deploy to Netlify Functions with automatic configuration:

astro.config.mjs

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

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

Cloudflare Adapter

Deploy to Cloudflare Workers for edge computing:

astro.config.mjs

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

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

Hybrid Rendering

Use hybrid mode to pre-render most pages while keeping specific routes dynamic:

astro.config.mjs

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

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

Then mark specific pages as server-rendered:

src/pages/api/user.astro

---
export const prerender = false;

const user = await fetchUserData(Astro.request);
---

<div>{user.name}</div>

Environment Variables

Managing Secrets

Create a .env file for local development:

.env

DATABASE_URL=postgresql://localhost/mydb
API_KEY=secret_key_here

Access them in your code:

---
const apiKey = import.meta.env.API_KEY;
---

Important: Never commit .env files. Add them to .gitignore.

Public vs Private Variables

Variables prefixed with PUBLIC_ are exposed to the browser:

.env

PUBLIC_API_ENDPOINT=https://api.example.com
PRIVATE_API_KEY=secret123

---
// Available server-side only
const privateKey = import.meta.env.PRIVATE_API_KEY;
---

<script>
  // Available in browser
  const endpoint = import.meta.env.PUBLIC_API_ENDPOINT;
</script>

Build Output

The dist/ directory structure varies by output mode:

Static Output:

dist/
├── index.html
├── about.html
├── _astro/
│   ├── styles.*.css
│   └── scripts.*.js
└── assets/

Server Output:

dist/
├── client/
│   └── _astro/
└── server/
    └── entry.mjs

Deployment Checklist

1. Set your site URL

   Configure the site option in astro.config.mjs for proper canonical URLs and sitemap generation.

2. Optimize assets

   Ensure images use the <Image> component for automatic optimization.

3. Configure environment variables

   Set production environment variables in your hosting provider’s dashboard.

4. Test the build locally

   Run astro build && astro preview to test the production build before deploying.

5. Set up CI/CD

   Configure automatic deployments from your Git repository for streamlined updates.

Troubleshooting

Build fails with module errors

Ensure all dependencies are listed in package.json and not just in devDependencies. Server-side code needs production dependencies.

404 errors on deployed site

Check that your hosting provider is configured to handle client-side routing. For SPAs, you may need a redirect rule to send all requests to index.html.

Environment variables not working

Verify that variables are set in your hosting provider’s dashboard. Remember that PUBLIC_ prefix is required for client-side access.