How to deploy SvelteKit to GitHub Pages

In short

The settings

Pages source

GitHub Actions

Build

npm run build

Folder it publishes

build

Live at

USERNAME.github.io/REPO

Step by step

Set it up

1. 1

   Set up SvelteKit for a static build

   Install the static adapter (npm i -D @sveltejs/adapter-static), use it in your config, and add export const prerender = true; to src/routes/+layout.js so every page is built to a file.

   import adapter from '@sveltejs/adapter-static';
   import { sveltekit } from '@sveltejs/kit/vite';
   import { defineConfig } from 'vite';
   
   export default defineConfig({
     plugins: [
       sveltekit({
         adapter: adapter(),
       }),
     ],
   });

2. 2

   Set the base path

   A GitHub Pages project site lives in a subfolder, USERNAME.github.io/REPO, so the build has to know that folder's name.

   Give the adapter a 404.html fallback and read the base path from the BASE_PATH variable the workflow sets.

   sveltekit({
     adapter: adapter({ fallback: '404.html' }),
     paths: { base: process.env.BASE_PATH ?? '' },
   }),

3. 3

   Add the workflow

   Create .github/workflows/deploy.yml in the repository with the file below. It builds the site on every push to main and publishes the result.

   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   concurrency:
     group: pages
     cancel-in-progress: false
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with:
             node-version: lts/*
             cache: npm
         - id: pages
           uses: actions/configure-pages@v6
         - run: npm ci
         - name: Build
           run: npm run build
           env:
             BASE_PATH: "/${{ github.event.repository.name }}"
         - uses: actions/upload-pages-artifact@v5
           with:
             path: build
   
     deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - id: deployment
           uses: actions/deploy-pages@v5
   

4. 4

   Switch Pages to GitHub Actions

   In the repository on GitHub, open the Pages settings and set the source to GitHub Actions. This is a one-time switch.

   Settings→Pages→Build and deployment→Source: GitHub Actions

5. 5

   Push, then open your site

   Commit and push to main. The Actions tab shows the build; when it turns green, the site is at https://USERNAME.github.io/REPO/. Every push after that deploys again.

Good to know

Common snags

• SvelteKit 2 keeps the adapter in svelte.config.js under kit.adapter; SvelteKit 3 moved it into the sveltekit() plugin in vite.config.js, as shown here. The options are the same.
• The workflow uses npm. With pnpm or Yarn, change the install line and the cache setting to match.

Questions

Before you start

Next step: connect your own domain to GitHub Pages.