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 thedist
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",
"preview": "astro preview"
}
}
Building The App
Section titled Building The AppYou 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
Section titled GitHub PagesYou can deploy an Astro site to GitHub Pages by using GitHub Actions to automatically build and deploy your site. To do this, your source repository must be hosted on GitHub.
-
Set the
site
and, if needed,base
options inastro.config.mjs
.site
should be something likehttps://<YOUR USERNAME>.github.io/
base
should be your repository’s name. (If your repository is named<YOUR USERNAME>.github.io
, you don’t need to includebase
.)
-
Create a new file in your project at
.github/workflows/deploy.yml
and paste in the YAML below.name: Github Pages Astro CI on: # Trigger the workflow every time you push to the `main` branch # Using a different branch name? Replace `main` with your branch’s name push: branches: [main] # Allows you to run this workflow manually from the Actions tab on GitHub. workflow_dispatch: jobs: deploy: runs-on: ubuntu-20.04 # Allow this job to push changes to your repository permissions: contents: write steps: - name: Check out your repository using git uses: actions/checkout@v2 - name: Use Node.js 16 uses: actions/setup-node@v2 with: node-version: 16 # Not using npm? Change `npm ci` to `yarn install` or `pnpm i` - name: Install dependencies run: npm ci # Not using npm? Change `npm run build` to `yarn build` or `pnpm run build` - name: Build Astro run: npm run build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} # `./dist` is the default Astro build directory. # If you changed that, update it here too. publish_dir: ./dist
See the GitHub Pages Action documentation for different ways you can configure the final “Deploy to GitHub Pages” step.
-
Commit the new workflow file and push it to GitHub.
-
On GitHub, go to your repository’s Settings tab and find the Pages section of the settings.
-
Choose the
gh-pages
branch as the Source of your site and press Save.
Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you.
Travis CI
Section titled Travis CI-
Set the correct
.site
inastro.config.mjs
. -
Create a file named
.travis.yml
in the root of your project. -
Run
npm install
locally and commit the generated lockfile (package-lock.json
). -
Use the GitHub Pages deploy provider template, and follow the Travis CI documentation.
language: node_js node_js: - lts/* install: - npm ci script: - npm run build deploy: 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 on: branch: master
GitLab Pages
Section titled GitLab Pages-
Set the correct
.site
inastro.config.mjs
. -
Set
dist
inastro.config.mjs
topublic
andpublic
inastro.config.mjs
to a newly named folder that is holding everything currently inpublic
. The reasoning is becausepublic
is a second source folder in astro, so if you would like to output topublic
you’ll need to pull public assets from a different folder. Yourastro.config.mjs
might end up looking like this:export default defineConfig({ sitemap: true, site: 'https://astro.build/', });
-
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:14 pages: cache: paths: - node_modules/ script: - npm install - npm run build artifacts: paths: - public only: - main
Netlify
Section titled NetlifyNote: If you are using an older build image on Netlify, make sure that you set your Node.js version in either a .nvmrc
file (example: node v14.17.6
) or a NODE_VERSION
environment variable. This step is no longer required by default.
You can configure your deployment in two ways, via the Netlify website or with a local project netlify.toml
file.
netlify.toml
file
Section titled netlify.toml fileCreate a new netlify.toml
file at the top level of your project repository with the following settings:
[build]
command = "npm run build"
publish = "dist"
Using pnpm
on Netlify? Use the following settings instead:
[build.environment]
NPM_FLAGS = "--version" # prevent Netlify npm install
[build]
command = 'npx pnpm i --store=node_modules/.pnpm-store && npm run build'
publish = 'dist'
Push the new netlify.toml
file up to your hosted git repository. Then, set up a new project on Netlify for your git repository. Netlify will read this file and automatically configure your deployment.
Netlify Website UI
Section titled Netlify Website UIYou can skip the netlify.toml
file and go directly to Netlify to configure your project. Netlify should now detect Astro projects automatically and pre-fill the configuration for you. Make sure that the following settings are entered before hitting the “Deploy” button:
- Build Command:
astro build
ornpm run build
- Publish directory:
dist
Google Cloud
Section titled Google CloudDifferent from most available deploy options here, Google Cloud requires some UI clicks to deploy projects. (Most of these actions can also be done using the gcloud CLI).
Cloud Run
Section titled Cloud Run-
Create a new GCP project, or select one you already have.
-
Make sure the Cloud Run API is enabled.
-
Create a new service.
-
Use a container from Docker Hub or build your own using Cloud Build.
-
Configure a port from which the files are served.
-
Enable public access by adding a new permission to
allUsers
calledCloud Run Invoker
.
Cloud Storage
Section titled Cloud Storage-
Create a new GCP project, or select one you already have.
-
Create a new bucket under Cloud Storage.
-
Give it a name and other required settings.
-
Upload your
dist
folder into it or upload using Cloud Build. -
Enable public access by adding a new permission to
allUsers
calledStorage Object Viewer
. -
Edit the website configuration and add
ìndex.html
as entrypoint and404.html
as errorpage.
Google Firebase
Section titled Google Firebase-
Make sure you have firebase-tools installed.
-
Create
firebase.json
and.firebaserc
at the root of your project with the following content:firebase.json
:{ "hosting": { "public": "dist", "ignore": [] } }
.firebaserc
:{ "projects": { "default": "<YOUR_FIREBASE_ID>" } }
-
After running
npm run build
, deploy using the commandfirebase deploy
.
Surge
Section titled Surge-
First install surge, if you haven’t already.
-
Run
npm run build
. -
Deploy to surge by typing
surge dist
.
You can also deploy to a custom domain by adding surge dist yourdomain.com
.
Heroku
Section titled Heroku-
Install Heroku CLI.
-
Create a Heroku account by signing up.
-
Run
heroku login
and fill in your Heroku credentials:$ heroku login
-
Create a file called
static.json
in the root of your project with the below content:static.json
:{ "root": "./dist" }
This is the configuration of your site; read more at heroku-buildpack-static.
-
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 https://github.com/heroku/heroku-buildpack-static.git
-
Deploy your site:
# publish site $ git push heroku master # opens a browser to view the Dashboard version of Heroku CI $ heroku open
Vercel
Section titled VercelYou can deploy Astro to Vercel through the CLI or the Vercel git integrations with zero-configuration.
- Install the Vercel CLI and run
vercel
to deploy. - Vercel will automatically detect Astro and configure the right settings.
- When asked
Want to override the settings? [y/N]
, chooseN
. - Your application is deployed! (e.g. astro.vercel.app)
$ npm i -g vercel
$ vercel
- Push your code to your git repository (GitHub, GitLab, BitBucket).
- Import your project into Vercel.
- Vercel will automatically detect Astro and configure the right settings.
- Your application is deployed! (e.g. astro.vercel.app)
After your project has been imported and deployed, 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.
Learn more about Vercel’s Git Integration.
Azure Static Web Apps
Section titled Azure Static Web AppsYou can deploy your Astro project with Microsoft Azure Static Web Apps service. You need:
- An Azure account and a subscription key. You can create a free Azure account here.
- Your app code pushed to GitHub.
- The SWA Extension in Visual Studio Code.
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.
Cloudflare Pages
Section titled Cloudflare PagesYou can deploy your Astro project on Cloudflare Pages. You need:
- A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process.
- Your app code pushed to a GitHub or a GitLab repository.
Then, set up a new project on Cloudflare Pages.
Use the following build settings:
- Framework preset:
Astro
- Build command:
npm run build
- Build output directory:
dist
- Environment variables (advanced): Currently, Cloudflare Pages supports
NODE_VERSION = 12.18.0
in the Pages build environment by default. Astro requires14.15.0
,v16.0.0
, or higher. You can add an environment variable with the Variable name ofNODE_VERSION
and a Value of a Node version that’s compatible with Astro or by specifying the node version of your project in a.nvmrc
or.node-version
file.
Then click the Save and Deploy button.
Render
Section titled RenderYou can deploy your Astro project on Render following these steps:
- Create a render.com account and sign in
- Click the New + button from your dashboard and select Static Site
- Connect your GitHub or GitLab repository or alternatively enter the public URL of a public repository
- Give your website a name, select the branch and specify the build command and publish directory
- build command:
npm run build
- publish directory:
dist
- build command:
- Click the Create Static Site button
Buddy
Section titled BuddyYou can deploy your Astro project using Buddy. To do so you’ll need to:
-
Create a Buddy account here.
-
Create a new project and connect it with a git repository (GitHub, GitLab, BitBucket, any private Git Repository or you can use Buddy Git Hosting).
-
Add a new pipeline.
-
In the newly created pipeline add a Node.js action.
-
In this action add:
npm install npm run build
-
Add a deployment action - there are many to choose from, you can browse them here. Although their can settings differ, remember to set the Source path to
dist
. -
Press the Run button.
Layer0
Section titled Layer0You can deploy your Astro project using the steps in the following sections.
Create the Astro Site
Section titled Create the Astro SiteIf you don’t have an existing Astro site, you can create one by running:
# prepare for liftoff...
npm create astro@latest
# install dependencies
npm install
# start developing!
npm run dev
# when you're ready: build your static site to `dist/`
npm run build
Add Layer0
Section titled Add Layer0# First, globally install the Layer0 CLI:
$ npm i -g @layer0/cli
# Then, add Layer0 to your Astro site:
$ 0 init
Update your Layer0 Router
Section titled Update your Layer0 RouterPaste the following into routes.ts:
// routes.ts
import { Router } from '@layer0/core';
export default new Router()
.get(
'/:path*/:file.:ext(js|css|png|ico|jpg|gif|svg)',
({ cache, serveStatic }) => {
cache({
browser: {
// cache js, css, and images in the browser for one hour...
maxAgeSeconds: 60 * 60,
},
edge: {
// ... and at the edge for one year
maxAgeSeconds: 60 * 60 * 24 * 365,
},
});
serveStatic('dist/:path*/:file.:ext');
}
)
.match('/:path*', ({ cache, serveStatic, setResponseHeader }) => {
cache({
// prevent the browser from caching html...
browser: false,
edge: {
// ...cache html at the edge for one year
maxAgeSeconds: 60 * 60 * 24 * 365,
},
});
setResponseHeader('content-type', 'text/html; charset=UTF-8');
serveStatic('dist/:path*');
});
You can remove the origin backend from layer0.config.js
:
module.exports = {};
Deploy to Layer0
Section titled Deploy to Layer0To deploy your site to Layer0, run:
# Create a production build of your astro site
$ npm run build
# Deploy it to Layer0
$ 0 deploy
Credits
Section titled CreditsThis guide was originally based off Vite’s well-documented static deploy guide.