Skip to main content

​
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()],
});

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

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

Ensure all dependencies are listed in package.json and not just in devDependencies. Server-side code needs production dependencies.
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.
Verify that variables are set in your hosting provider’s dashboard. Remember that PUBLIC_ prefix is required for client-side access.

Build docs developers (and LLMs) love

Get started for freeTalk to us