Deployment and custom domains

npm run build writes a static site to dist/. There is no server code, so any host that serves static files can publish it.

Three settings are the same on every host:

The hosts named on this page are examples. This page does not describe their dashboards, because those change; each host’s own documentation is the authority. Astro keeps a guide for each of them at docs.astro.build/en/guides/deploy.

A host that builds from your repository#

Services such as Vercel, Netlify and Cloudflare Pages can build the site each time you push to your Git repository. The general steps:

1. Push the project to a Git repository.
2. Create a project on the host and connect the repository.
3. Enter the three settings from the table above. If the host asks how to choose the Node.js version, see its documentation; the theme’s .nvmrc file names Node 22.
4. If you use them, add the environment variables from .env.example in the host’s settings: SITE_URL, SITE_BASE, PUBLIC_CONTACT_FORM_ACTION and PUBLIC_NEWSLETTER_FORM_ACTION. They are read when the site is built, so build again after changing one.
5. Deploy.

GitHub Pages#

A project site on GitHub Pages is served from a sub-path: https://<username>.github.io/<repository>/. The theme reads the base path from SITE_BASE and the origin from SITE_URL, and every internal link, font and file address follows them.

Create .github/workflows/deploy.yml. The workflow below follows Astro’s guide, Deploy your Astro site to GitHub Pages, as read on 2026-10-14, with the two variables added. Check that guide for newer action versions before you use it.

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 your repository using git
        uses: actions/checkout@v7
      - name: Install, build, and upload your site
        uses: withastro/action@v6
        env:
          SITE_BASE: '/${{ github.event.repository.name }}'
          SITE_URL: 'https://${{ github.repository_owner }}.github.io'

  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@v5

Then, in the repository on GitHub, open Settings, then Pages, and choose GitHub Actions as the source.

Two notes:

• That guide says the action picks the package manager from the lockfile, so keep package-lock.json in the repository, and that it uses Node 24 unless you set node-version. The theme needs 22.12.0 or newer.
• If the repository is named <username>.github.io, or you use a custom domain, the site is served from the root: leave SITE_BASE out.

Your own domain#

1. Set url in src/site.config.ts to the address visitors will use (or set SITE_URL where the site is built). Canonical links, social tags, sitemap.xml and robots.txt are built from it.

   ts

   export const siteConfig: SiteConfig = {
     url: 'https://example.com',
     // ...
   };

2. Add the domain in your host’s settings and create the DNS records the host asks for. On GitHub Pages, also add a file named CNAME to public/ that holds only the domain (for example example.com), as Astro’s GitHub Pages guide describes.

3. Build and deploy again, so the pages carry the new address.

Check the build first#

npm run check
npm run build
npm run preview

npm run preview serves the built site from dist/ on your machine, so you can click through it before you publish.