Build and Deploy an Astro Site with GitHub

Use this when starting a new Astro site that should be pushed to GitHub and deployed from a connected Git repository.

Create the Astro site

Create the project and enter the new app directory.

npm create astro@latest APP_NAME
cd APP_NAME

Install dependencies

Install packages if the setup command did not already do it.

npm install

Run the app locally

Start the dev server and check the site in the browser.

npm run dev

Build the site

Run a production build before pushing or deploying.

npm run build

Preview the production build

Use preview when you want to check the built site locally.

npm run preview

Push `main` to GitHub

Create an empty GitHub repo first, then add the SSH remote and push main. This assumes Git was initialized when creating the Astro project. Astro usually creates the initial commit for you, so there may be nothing to add or commit here.

git branch -M main
git remote add origin git@github.com:USERNAME/REPO.git
git push -u origin main

Deploy from GitHub

Connect the GitHub repo to the deployment provider and use the standard Astro build settings.

Build command: npm run build
Output directory: dist

Deploy with Cloudflare Pages

Cloudflare Pages is a good default choice for a static Astro site. In Cloudflare, go to Workers & Pages, create a Pages application, and import the existing GitHub repository.

Use these build settings:

Production branch: main
Build command: npm run build
Build directory: dist

After the first deploy, Cloudflare Pages will build and deploy again when new commits are pushed to the connected branch.

Create and push `dev`

After main is pushed and deployed, create dev for regular development work.

git checkout -b dev
git push -u origin dev