Skip to main content
This guide covers deploying your Astro landing page to production. Astro generates static HTML files that can be hosted on any static site hosting service.

​
Build for Production

Before deploying, create an optimized production build: 
npm run build
This generates static files in the dist/ directory: 
dist/
├── favicon.ico
├── favicon.svg
└── index.html
The dist/ directory contains all files needed for deployment. These are optimized, minified, and ready for production.

​
Deployment Platforms

Choose a hosting platform based on your needs:

Vercel

Zero-config deployment with automatic HTTPS and CDN

Netlify

Continuous deployment with forms and serverless functions

Cloudflare Pages

Global CDN with lightning-fast performance

GitHub Pages

Free hosting directly from your GitHub repository

​
Vercel

1

Install Vercel CLI

npm install -g vercel
2

Deploy to Vercel

From your project root:
vercel
Follow the prompts to link your project.
3

Configure (if needed)

Vercel auto-detects Astro projects. If needed, create vercel.json:
vercel.json
{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "devCommand": "npm run dev",
  "installCommand": "npm install"
}

​
Continuous Deployment

Connect your Git repository for automatic deployments:
  1. Push your code to GitHub, GitLab, or Bitbucket
  2. Import the repository in the Vercel dashboard
  3. Vercel automatically deploys on every push to main
Preview deployments are created for pull requests, making it easy to review changes before merging.

​
Netlify

1

Install Netlify CLI

npm install -g netlify-cli
2

Build and deploy

npm run build
netlify deploy --prod
3

Configure build settings

Create netlify.toml in your project root:
netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

​
Git-based Deployment

  1. Push your code to a Git repository
  2. Log in to Netlify
  3. Click Add new site → Import an existing project
  4. Select your repository and configure:
    • Build command: npm run build
    • Publish directory: dist
  5. Click Deploy site
Netlify provides automatic HTTPS, custom domains, and form handling out of the box.

​
Cloudflare Pages

1

Create Cloudflare Pages project

  1. Log in to Cloudflare dashboard
  2. Go to Pages → Create a project
  3. Connect your Git repository
2

Configure build settings

Set the following configuration:
  • Framework preset: Astro
  • Build command: npm run build
  • Build output directory: dist
3

Deploy

Click Save and Deploy. Cloudflare builds and deploys your site.

​
Using Wrangler CLI

Deploy directly from the command line: 
# Install Wrangler
npm install -g wrangler

# Build your site
npm run build

# Deploy to Cloudflare Pages
wrangler pages deploy dist
Cloudflare Pages offers unlimited bandwidth and automatic SSL certificates.

​
GitHub Pages

1

Update astro.config.mjs

Add your repository name as the site base:
astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://username.github.io',
  base: '/repository-name',
});
Replace username with your GitHub username and repository-name with your repo name.
2

Create GitHub Actions workflow

Create .github/workflows/deploy.yml:
.github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
3

Enable GitHub Pages

  1. Go to repository Settings → Pages
  2. Under Source, select GitHub Actions
  3. Push to main branch to trigger deployment

​
Other Platforms

​
AWS S3 + CloudFront

# Build the site
npm run build

# Sync to S3 bucket
aws s3 sync dist/ s3://your-bucket-name --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation --distribution-id YOUR_DIST_ID --paths "/*"

​
DigitalOcean App Platform

  1. Create new app from your Git repository
  2. Configure build settings:
    • Build command: npm run build
    • Output directory: dist
  3. Deploy

​
Firebase Hosting

# Install Firebase CLI
npm install -g firebase-tools

# Initialize Firebase
firebase init hosting

# Build and deploy
npm run build
firebase deploy
Configure firebase.json:
firebase.json
{
  "hosting": {
    "public": "dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
  }
}

​
Environment Variables

If your landing page uses environment variables: 
PUBLIC_API_URL=https://api.example.com
PUBLIC_SITE_URL=https://example.com
Prefix public variables with PUBLIC_ in Astro. Never commit .env files containing secrets.

​
Platform-specific Configuration

Add environment variables in project settings:
  1. Go to Settings → Environment Variables
  2. Add each variable with appropriate scope (Production, Preview, Development)
Add variables in site settings:
  1. Go to Site settings → Environment variables
  2. Click Add a variable and enter key-value pairs
Add via dashboard or Wrangler:
wrangler pages secret put PUBLIC_API_URL
Use repository secrets:
  1. Go to Settings → Secrets and variables → Actions
  2. Add secrets and reference in workflow:
- name: Build
  run: npm run build
  env:
    PUBLIC_API_URL: ${{ secrets.PUBLIC_API_URL }}

​
Custom Domains

All major platforms support custom domains:
1

Update site configuration

Set your domain in astro.config.mjs:
export default defineConfig({
  site: 'https://yourdomain.com',
});
2

Configure DNS

Add DNS records for your domain:For Vercel/Netlify:
  • A record pointing to their IP
  • CNAME for www subdomain
For Cloudflare Pages:
  • CNAME pointing to your Pages URL
3

Enable HTTPS

Most platforms provide automatic SSL certificates via Let’s Encrypt.

​
Performance Optimization

Enable caching

Configure cache headers for static assets

Use CDN

Most platforms include global CDN by default

Compress assets

Enable Brotli/Gzip compression

Optimize images

Use Astro’s image optimization features

​
Deployment Checklist

Before deploying to production:
  • Run npm run build successfully
  • Test with npm run preview
  • Verify all environment variables are set
  • Check that custom domain is configured
  • Confirm HTTPS is enabled
  • Test site on multiple devices and browsers
  • Verify analytics and tracking codes work
  • Check meta tags and SEO settings

​
Troubleshooting

Ensure your hosting platform serves index.html for all routes. Add redirects if needed:Netlify: Already configured in netlify.toml aboveVercel: Create vercel.json:
{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
Check the base option in astro.config.mjs matches your deployment path.
  1. Verify Node.js version matches your local environment
  2. Check build logs for specific errors
  3. Ensure all dependencies are in package.json (not devDependencies for build tools)
  • Prefix public variables with PUBLIC_
  • Rebuild after changing environment variables
  • Check platform-specific syntax for accessing variables

​
Next Steps

Your landing page is now live! Consider:
  • Setting up analytics and monitoring with your preferred service
  • Configuring custom domains and SSL through your hosting platform
  • Implementing performance optimizations for faster load times

Build docs developers (and LLMs) love

Get started for freeTalk to us