sveltekit-gh-pages

Minimal static SvelteKit set-up made deployable to GitHub Pages.

1) Use the static adapter

Install the SvelteKit static adapter to prerender the app.

package.json

  "devDependencies": {
+   "@sveltejs/adapter-static": "^3.0.1",
    "@sveltejs/kit": "^2.5.4",
    "@sveltejs/vite-plugin-svelte": "^3.0.2",
    "gh-pages": "^6.1.1",
    "svelte": "^4.2.12",
    "vite": "^5.1.6"
  }

svelte.config.js

+ import adapter from "@sveltejs/adapter-static";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
+   adapter: adapter(),
  },
};

export default config;

Ensure your top-level +layout.js exports prerender = true. Note that for SvelteKit version 2, trailingSlash should be set to "always" so that the app does not redirect the URL to /about.

// src/routes/+layout.js
export const prerender = true;

export const trailingSlash = "always";

2) Modify paths.base in the config

kit.paths.base should be your repo URL subpath (see the Vite docs). In the example below, replace /sveltekit-gh-pages with your repository name.

import adapter from "@sveltejs/adapter-static";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter(),
+   paths: {
+     base: process.env.NODE_ENV === "production" ? "/sveltekit-gh-pages" : "",
+   },
  },
};

export default config;

Note: You will also need to prepend relative paths with the SvelteKit base path so that your app can build successfully for production.

<script>
  import { base } from "$app/paths";
</script>

<a href="{base}/about">About</a>

3) Add a .nojekyll file to the /static folder

The last step is to add an empty .nojekyll file to the static folder to bypass Jekyll on GitHub Pages. SvelteKit will copy static assets to the final build folder.

package.json

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "deploy": "gh-pages -d build -t true"
  }
}

The deploy script

The deploy script instructs gh-pages to do the following:

• -d build: Publish the build folder
• -t true: Include dotfiles (e.g., .nojekyll)

Quick start

Use degit to quickly scaffold a new project from this repository:

npx degit metonym/sveltekit-gh-pages my-app
cd my-app && npm install

Deploying to GitHub Pages

First, build the app by running npm run build.

Then, run npm run deploy to deploy the app to GitHub Pages.