Deploy a Website

The following guides are based on some shared assumptions:

  • You are using the default build output location (dist/). This location can be changed using the dist configuration option.
  • You are using npm. You can use equivalent commands to run the scripts if you are using Yarn or other package managers.
  • Astro is installed as a local dev dependency in your project, and you have set up the following npm scripts:
  "scripts": {
    "start": "astro dev",
    "build": "astro build"

Building The App

You may run npm run build command to build the app.

$ npm run build

By default, the build output will be placed at dist/. You may deploy this dist/ folder to any of your preferred platforms.

GitHub Pages

  1. Set the correct in astro.config.mjs.

  2. Inside your project, create with the following content (uncommenting the appropriate lines), and run it to deploy:

    #!/usr/bin/env sh
    # abort on errors
    set -e
    # build
    npm run build
    # navigate into the build output directory
    cd dist
    # add .nojekyll to bypass GitHub Page's default behavior
    touch .nojekyll
    # if you are deploying to a custom domain
    # echo '' > CNAME
    git init
    git add -A
    git commit -m 'deploy'
    # if you are deploying to https://<USERNAME>
    # git push -f<USERNAME>/<USERNAME> main
    # if you are deploying to https://<USERNAME><REPO>
    # git push -f<USERNAME>/<REPO>.git main:gh-pages
    cd -

    You can also run the above script in your CI setup to enable automatic deployment on each push.

GitHub Actions

  1. Set the correct in astro.config.mjs
  2. Create the file .github/workflows/main.yml and add in the yaml below. Make sure to edit in your own details.
  3. In Github go to Settings > Developer settings > Personal Access tokens. Generate a new token with repo permissions.
  4. In the astro project repo (not <YOUR USERNAME> go to Settings > Secrets and add your new personal access token with the name API_TOKEN_GITHUB.
  5. When you push changes to the astro project repo CI will deploy them to <YOUR USERNAME> for you.
# Workflow to build and deploy to your Github Pages repo.

# Edit your project details here.
# Remember to add API_TOKEN_GITHUB in repo Settings > Secrets as well!

name: Github Pages Astro CI

  # Triggers the workflow on push and pull request events but only for the main branch
    branches: [main]
    branches: [main]

  # Allows you to run this workflow manually from the Actions tab.

    runs-on: ubuntu-latest

      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      # Install dependencies with npm
      - name: Install dependencies
        run: npm ci

      # Build the project and add .nojekyll file to supress default behaviour
      - name: Build
        run: |
          npm run build
          touch ./dist/.nojekyll

      # Push to your pages repo
      - name: Push to pages repo
        uses: cpina/github-action-push-to-another-repository@main
          API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
          source-directory: 'dist'
          destination-github-username: ${{ }}
          destination-repository-name: ${{ env.deployToRepo }}
          user-email: ${{ env.githubEmail }}
          commit-message: Deploy ORIGIN_COMMIT
          target-branch: main

Travis CI

  1. Set the correct in astro.config.mjs.

  2. Create a file named .travis.yml in the root of your project.

  3. Run npm install locally and commit the generated lockfile (package-lock.json).

  4. Use the GitHub Pages deploy provider template, and follow the Travis CI documentation.

    language: node_js
      - lts/*
      - npm ci
      - npm run build
      provider: pages
      skip_cleanup: true
      local_dir: dist
      # A token generated on GitHub allowing Travis to push code on you repository.
      # Set in the Travis settings page of your repository, as a secure variable.
      github_token: $GITHUB_TOKEN
      keep_history: true
        branch: master

GitLab Pages

  1. Set the correct in astro.config.mjs.

  2. Set build.outDir in astro.config.mjs to public.

  3. Create a file called .gitlab-ci.yml in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:

    image: node:10.22.0
          - node_modules/
        - npm install
        - npm run build
          - public
        - master


In your codebase, make sure you have a .nvmrc file with v14.15.1 in it.

You can configure your deploy in two ways, via the Netlify website or with the netlify.toml file.

With the netlify.toml file, add it at the top level of your project with the following settings:

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

Then, set up a new project on Netlify from your chosen Git provider.

If you don’t want to use the netlify.toml, when you go to Netlify and set up a new project from Git, input the following settings:

  • Build Command:astro build or npm run build
  • Publish directory:dist

Then hit the deploy button.

Google Firebase

  1. Make sure you have firebase-tools installed.

  2. Create firebase.json and .firebaserc at the root of your project with the following content:


      "hosting": {
        "public": "dist",
        "ignore": []


     "projects": {
       "default": "<YOUR_FIREBASE_ID>"
  3. After running npm run build, deploy using the command firebase deploy.


  1. First install surge, if you haven’t already.

  2. Run npm run build.

  3. Deploy to surge by typing surge dist.

You can also deploy to a custom domain by adding surge dist


  1. Install Heroku CLI.

  2. Create a Heroku account by signing up.

  3. Run heroku login and fill in your Heroku credentials:

    $ heroku login
  4. Create a file called static.json in the root of your project with the below content:


      "root": "./dist"

    This is the configuration of your site; read more at heroku-buildpack-static.

  5. Set up your Heroku git remote:

    # version change
    $ git init
    $ git add .
    $ git commit -m "My site ready for deployment."
    # creates a new app with a specified name
    $ heroku apps:create example
    # set buildpack for static sites
    $ heroku buildpacks:set
  6. Deploy your site:

    # publish site
    $ git push heroku master
    # opens a browser to view the Dashboard version of Heroku CI
    $ heroku open


To deploy your Astro project with a Vercel for Git, make sure it has been pushed to a Git repository.

Go to and import the project into Vercel using your Git of choice (GitHub, GitLab or BitBucket). Follow the wizard to select the project root with the project’s package.json and override the build step using npm run build and the output dir to be ./dist

After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly “main”) will result in a Production Deployment.

Once deployed, you will get a URL to see your app live, such as the following:

Azure Static Web Apps

You can deploy your Astro project with Microsoft Azure Static Web Apps service. You need:

Install the extension in VS Code and navigate to your app root. Open the Static Web Apps extension, sign in to Azure, and click the ’+’ sign to create a new Static Web App. You will be prompted to designate which subscription key to use.

Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually /) and built file location /dist. The wizard will run and will create a GitHub action in your repo in a .github folder.

The action will work to deploy your app (watch its progress in your repo’s Actions tab) and, when successfully completed, you can view your app in the address provided in the extension’s progress window by clicking the ‘Browse Website’ button that appears when the GitHub action has run.


This guide was originally based off of Vite’s well-documented static deploy guide.