Astro Deployment — Deploy to Production Hosting

In this tutorial, you will learn about Astro Deployment. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Astro deployment: deploy to Netlify, Vercel, Cloudflare Pages, or Node.js servers with SSR adapters and CI/CD pipelines.

In this lesson, you'll configure deployment adapters, build your Astro site for production, deploy to popular hosting platforms, and set up continuous deployment.

What You'll Learn

How to build for production, configure platform adapters for SSR, deploy to static hosts, and set up CI/CD with Git-based deployment.

Why It Matters

Proper deployment ensures your site is accessible, fast, and automatically updated when you push changes to your repository.

Real-World Use

DodaTech deploys its tutorial site to Netlify with automatic builds on every Git push, serving millions of page views per month.

flowchart LR
    A[Git Push] --> B[CI Build]
    B --> C[Adapter Config]
    C --> D[Hosting Platform]
    D --> E[Live Site]
    style D fill:#ff5a03,color:#fff

Static Deployment

Build and deploy to any static host:

npm run build
# Output in dist/

Deploy the dist/ folder to Netlify, Vercel, Cloudflare Pages, GitHub Pages, or any static file host.

Netlify Deployment

Install the Netlify Adapter:

npx astro add netlify

Configure:

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

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

For static sites, no adapter is needed. Connect your Git repository to Netlify and set build command to npm run build and publish directory to dist.

Vercel Deployment

Install the Vercel adapter:

npx astro add vercel

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

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

Cloudflare Pages

Install the Cloudflare adapter:

npx astro add cloudflare

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

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

Node.js Deployment

Run your SSR site on any Node.js server:

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

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

Start the server:

node ./dist/server/entry.mjs

Environment Variables

Use environment variables for different deployment environments:

---
const apiUrl = import.meta.env.API_URL || "https://api.example.com";
---

Set variables in your hosting dashboard (Netlify, Vercel) or .env file.

Common Mistakes

1. Deploying without building: Always run npm run build before deploying. The dist/ directory must be up to date.
2. Missing environment variables: API keys and database URLs must be set in the hosting platform's environment settings.
3. Using SSR without a compatible host: SSR requires Node.js or Edge runtime. Some static hosts only support static output.
4. Not configuring redirects: For SPAs or custom routing, add redirect rules (_redirects for Netlify, vercel.json for Vercel).
5. Forgetting to set site in config: RSS, sitemap, and canonical URLs depend on the site URL. Set it before deployment.

Practice Questions

1. What is the build output directory? Answer: dist/ for static sites, or .vercel/output/ for Vercel SSR builds.

2. How do you deploy an Astro SSR site to Netlify? Answer: Add @astrojs/netlify adapter, set output: "server", and connect your Git repo to Netlify.

3. What is the purpose of adapters? Answer: Adapters configure Astro's SSR output for specific hosting platforms, handling request/response formats and deployment specifics.

4. How do you use environment variables in Astro? Answer: Access them via import.meta.env.VARIABLE_NAME. Prefix public variables with PUBLIC_.

Challenge

Deploy an Astro SSR site to two different platforms: static output to Netlify and SSR output to a Node.js server. Compare the deployment processes.

Mini Project

Set up a complete deployment pipeline for a blog site with automatic builds on Git push, staging preview deployments for pull requests, and production deployment from the main branch.

FAQ

What's Next

Learn about Astro Testing for testing Astro components and pages.