Astro Starlight Deployment Workflow

What You Are Learning

This tutorial explains the deployment workflow for an Astro Starlight site.

You will learn how to:

• Build the site locally.
• Preview the production build.
• Understand the dist/ output folder.
• Deploy to Vercel.
• Deploy to Netlify.
• Deploy to Cloudflare Pages or Workers.
• Use environment variables safely.
• Fix common build and deployment errors.

Big Picture Mental Model

Deployment means turning your source code into a published website.

Source files
  ↓
npm install
  ↓
npm run build
  ↓
dist/ folder
  ↓
Hosting platform
  ↓
Live website URL

For a mostly static Astro Starlight site, the most important settings are usually:

Build command: npm run build
Output directory: dist

Deployment Vocabulary

Check Your Scripts

Open:

package.json

You should see scripts like:

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

These scripts are the foundation of the workflow:

npm run dev      local development
npm run build    production build
npm run preview  preview production build locally

Build Locally Before Deploying

Run:

npm install
npm run build

If the build succeeds, Astro creates:

dist/

Do not skip this step. A site can work in development but fail in production because of broken imports, invalid MDX, incorrect image paths, or missing environment variables.

Preview the Production Build

Run:

npm run preview

This serves the built site locally. Use this to check:

• Home page loads.
• Sidebar links work.
• Images load.
• MDX components render.
• Custom CSS is applied.
• No routes are missing.

Git Workflow Before Deployment

Most platforms deploy from GitHub, GitLab, or Bitbucket.

git status
git add .
git commit -m "Prepare Astro Starlight site for deployment"
git push

After you connect the repository to a host, future pushes usually trigger new deployments automatically.

General Static Deployment Settings

Deploy to Vercel

Vercel works well for Astro and Starlight sites.

1. Push your project to GitHub, GitLab, or Bitbucket.
2. Sign in to Vercel.
3. Create a new project.
4. Import the repository.
5. Confirm the project settings.
6. Deploy.

Common settings:

Framework preset: Astro
Build command: npm run build
Output directory: dist

Vercel usually detects Astro automatically, but always check the build command and output directory.

Deploy to Netlify

Netlify is also a strong choice for static Astro/Starlight sites.

1. Push your project to GitHub, GitLab, or Bitbucket.
2. Sign in to Netlify.
3. Create a new site from Git.
4. Select the repository.
5. Set build options.
6. Deploy.

Common settings:

Build command: npm run build
Publish directory: dist

You can also create a netlify.toml file:

[build]
  command = "npm run build"
  publish = "dist"

Deploy to Cloudflare Pages

For a static Astro Starlight site, Cloudflare Pages can deploy from a Git repository.

1. Push your project to a Git provider.
2. Open Cloudflare dashboard.
3. Create a Pages project.
4. Connect your repository.
5. Set the build command and output directory.
6. Deploy.

Common static settings:

Build command: npm run build
Output directory: dist

Some newer Cloudflare workflows use Workers and Wrangler. For a basic static documentation site, Pages-style Git deployment is usually simpler.

Deploy to Cloudflare Workers with Wrangler

Cloudflare also supports deploying Astro output with Wrangler, especially when using Workers-oriented workflows.

Install Wrangler:

npm install wrangler@latest --save-dev

A static wrangler.jsonc can point to the dist folder:

{
  "name": "my-astro-starlight-site",
  "compatibility_date": "2026-05-13",
  "assets": {
    "directory": "./dist"
  }
}

Preview and deploy:

npx astro build && npx wrangler dev
npx astro build && npx wrangler deploy

Use this route when you specifically want Cloudflare Workers features or a Wrangler-based workflow.

Environment Variables

Environment variables store settings outside your source code.

PUBLIC_SITE_NAME="Astro Starlight Tutorial Site"
PUBLIC_ANALYTICS_ID="example-id"
SECRET_API_KEY="do-not-expose-this"

Astro exposes environment variables prefixed with PUBLIC_ to browser code. Do not put secrets in public variables.

Static Site vs Server Features

Most Starlight documentation sites can be deployed as static sites. That means no custom adapter is needed.

Static docs site:
  npm run build
  output: dist
  deploy dist

If you add server-rendered routes, API routes, authentication, or runtime database calls, you may need an adapter for the hosting platform.

Mostly content and docs:
  static output is usually best

Runtime server features:
  consider an adapter

Base URL and Site URL

If your site is deployed at the root of a domain, the default setup is usually fine:

https://example.com/

If your site is deployed under a subpath, such as GitHub Pages, you may need a base setting:

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

export default defineConfig({
  site: 'https://example.com',
  base: '/my-docs/',
  integrations: [
    starlight({
      title: 'My Docs',
    }),
  ],
});

For Vercel, Netlify, and Cloudflare Pages custom domains, you usually do not need base.

Custom Domains

After deployment, most platforms let you add a custom domain.

example.com
www.example.com
docs.example.com

General process:

1. Add the domain in the hosting platform dashboard.
2. Update DNS records at the domain registrar.
3. Wait for DNS propagation.
4. Confirm HTTPS is active.

Deployment Checklist

[ ] npm install works
[ ] npm run dev works
[ ] npm run build works
[ ] npm run preview works
[ ] dist folder is created
[ ] Homepage loads
[ ] Sidebar links work
[ ] Images load
[ ] Custom CSS loads
[ ] Environment variables are configured
[ ] Repository is pushed to GitHub/GitLab/Bitbucket
[ ] Hosting platform build command is correct
[ ] Hosting platform output directory is dist

Common Problem: Build Fails Locally

Run:

npm install
npm run build

Common causes:

• Invalid Markdown or MDX.
• Broken component import path.
• Missing package.
• Invalid frontmatter.
• Schema validation error.

Fix the local build before trying to deploy.

Common Problem: Deployment Builds but Site Is Blank

Check:

• Output directory is dist.
• Build command is npm run build.
• The homepage exists.
• There is no incorrect base setting.
• Assets are referenced with correct paths.

Common Problem: Images Missing After Deployment

If images are in public/images/, reference them like this:

![Map](/images/map.png)

Do not reference local computer paths:

Bad:
C:\Users\Name\Desktop\map.png

Good:
/images/map.png

Common Problem: Environment Variable Undefined

Check:

• The variable exists in the hosting platform settings.
• The variable name matches exactly.
• You redeployed after adding the variable.
• Browser-visible variables use the PUBLIC_ prefix.

Common Problem: Wrong Node Version

If a platform uses an old Node version, the build may fail. You can specify a Node version in package.json:

{
  "engines": {
    "node": ">=20.0.0"
  }
}

Use a Node version supported by your current Astro version and hosting platform.

Preview Deployments

Preview deployments are temporary builds usually made from branches or pull requests.

main branch
  → production deployment

feature branch
  → preview deployment

Use preview deployments to test:

• New lessons.
• Sidebar changes.
• Theme changes.
• Content collection changes.
• Large world bible restructures.

Recommended Workflow for Ongoing Updates

1. Create or edit content locally.
2. Run npm run dev.
3. Check pages in the browser.
4. Run npm run build.
5. Run npm run preview.
6. Commit changes.
7. Push to GitHub.
8. Check preview deployment.
9. Merge or push to main.
10. Check production deployment.

Which Platform Should You Use?

For a beginner Astro Starlight site, Vercel or Netlify are usually the easiest. Cloudflare Pages is also excellent, especially if you already use Cloudflare DNS.

Manual Deployment

You can also deploy manually by uploading the built files.

npm run build

Then upload the contents of:

dist/

Use this method if your host only supports traditional file upload. Do not upload the project source files unless your host expects them.

Best Practices

• Always run npm run build before deploying important changes.
• Use npm run preview to test the production build locally.
• Keep deployment settings simple for static Starlight sites.
• Use dist as the output directory unless your project is intentionally configured otherwise.
• Do not commit secrets to Git.
• Use preview deployments for large changes.
• Check custom domains after DNS changes.
• Keep dependencies updated, but test builds after updates.

Mini Project: Deploy a Starlight Site

1. Run npm install.
2. Run npm run dev.
3. Check the site locally.
4. Run npm run build.
5. Run npm run preview.
6. Commit your changes.
7. Push to GitHub.
8. Import the repo into Vercel, Netlify, or Cloudflare Pages.
9. Set build command to npm run build.
10. Set output directory to dist.
11. Deploy.
12. Open the live URL and test the site.

Cheat Sheet

Simple Rule of Thumb

If it is a normal Starlight docs site:
  build with npm run build
  deploy the dist folder

If it needs server features:
  check whether your host needs an Astro adapter

If something breaks after deployment:
  test npm run build and npm run preview locally first