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

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

<Steps>
  <Step title="Build Your Site">
    Run the build command to create a production-ready version of your site:

    ```bash theme={null}
    astro build
    ```

    By default, this creates a `dist/` directory with your built site.
  </Step>

  <Step title="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
  </Step>

  <Step title="Deploy">
    Upload your `dist/` folder to your hosting provider or configure your adapter for automatic deployment.
  </Step>
</Steps>

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

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';

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

### Popular Static Hosting Providers

<CardGroup cols={2}>
  <Card title="Netlify" icon="globe">
    Drop-in support with zero configuration. Just connect your Git repository.
  </Card>

  <Card title="Vercel" icon="globe">
    Automatic deployments from Git with preview URLs for every commit.
  </Card>

  <Card title="Cloudflare Pages" icon="globe">
    Fast global CDN with unlimited bandwidth on the free tier.
  </Card>

  <Card title="GitHub Pages" icon="globe">
    Free hosting for public repositories with custom domain support.
  </Card>
</CardGroup>

## 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:

```js title="astro.config.mjs" theme={null}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

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

**Deployment Example:**

```bash theme={null}
# 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:

```js title="astro.config.mjs" theme={null}
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:

```js title="astro.config.mjs" theme={null}
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:

```js title="astro.config.mjs" theme={null}
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:

```js title="astro.config.mjs" theme={null}
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:

```astro title="src/pages/api/user.astro" theme={null}
---
export const prerender = false;

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

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

## Environment Variables

<Accordion title="Managing Secrets">
  Create a `.env` file for local development:

  ```bash title=".env" theme={null}
  DATABASE_URL=postgresql://localhost/mydb
  API_KEY=secret_key_here
  ```

  Access them in your code:

  ```astro theme={null}
  ---
  const apiKey = import.meta.env.API_KEY;
  ---
  ```

  **Important:** Never commit `.env` files. Add them to `.gitignore`.
</Accordion>

<Accordion title="Public vs Private Variables">
  Variables prefixed with `PUBLIC_` are exposed to the browser:

  ```bash title=".env" theme={null}
  PUBLIC_API_ENDPOINT=https://api.example.com
  PRIVATE_API_KEY=secret123
  ```

  ```astro theme={null}
  ---
  // 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>
  ```
</Accordion>

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

<Steps>
  <Step title="Set your site URL">
    Configure the `site` option in `astro.config.mjs` for proper canonical URLs and sitemap generation.
  </Step>

  <Step title="Optimize assets">
    Ensure images use the `<Image>` component for automatic optimization.
  </Step>

  <Step title="Configure environment variables">
    Set production environment variables in your hosting provider's dashboard.
  </Step>

  <Step title="Test the build locally">
    Run `astro build && astro preview` to test the production build before deploying.
  </Step>

  <Step title="Set up CI/CD">
    Configure automatic deployments from your Git repository for streamlined updates.
  </Step>
</Steps>

## Troubleshooting

<Accordion title="Build fails with module errors">
  Ensure all dependencies are listed in `package.json` and not just in `devDependencies`. Server-side code needs production dependencies.
</Accordion>

<Accordion title="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`.
</Accordion>

<Accordion title="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.
</Accordion>