How to Deploy SvelteKit Apps to Github Pages

SvelteKit is an app framework based around the popular Svelte component library. SvelteKit is really awesome. You can deploy SvelteKit apps to any server-based, serverless, or even static files host you want!

In this guide we’ll show you how you can deploy SvelteKit apps to Github Pages, a popular free way to host static files directly from a Github repository.

Getting Started

Want to get up and running right away? Just use this Github template repository. It has everything you need already set up. Once you have that you can skip to the Configure Github Pages section below.

Already have a Github repository you want to use but not SvelteKit? Skip to the Install SvelteKit section below.

Otherwise, you can continue with this section and learn how to create a SvelteKit Github repository from scratch. To do that we’ll need two things — a Github repository and a new SvelteKit project.

Create a new Github repository

First, let’s make a new Github repository.

Here’s a link to Github’s create new repository page (no repository will be made until you click the “Create repository” button on that page). The settings you should choose are:

• Repository name : Choose any name you like.

• Public / Private: If you have a free Github account, you’ll need to choose Public since Github only allows Github Pages hosting from public repositories for free accounts. If you have a paid Github Pro or Team account, you can choose either Public or Private.

• Add a README file: Optional. We’ll add a README later, but you can add one now if you like.

• Add .gitignore: Checked . Choose “Node ” from the “.gitignore template” dropdown. This will make it so that unnecessary files aren’t checked into your repository.

• Choose a license : Optional. Choose any license you want, or none. You can always add one later if you’re not sure.

Once you’re happy with your settings, click the Create repository button and you’ll have a new blank Github repository.

To get the repository on your computer, you can run git clone <repository url> in a terminal or use your favorite git software.

Install SvelteKit

Now we can install SvelteKit. Open a terminal to the Github repository on your computer and run the following command:

npm create svelte@latest

You’ll be walked through the configuration options for SvelteKit. You can choose any settings you want.

Then we need to install all the necessary SvelteKit packages:

npm install

Then we can add all these files to our Git repository:

git add -A && git commit -m "Initial commit"

And finally run the development server to test that everything is working:

npm run dev -- --open

Yay!

Configure Github Pages

Github Pages only allows sites to be hosted from either the root of a repository (/) or a /docs folder. Sites can also be hosted from any branch of a repository, but again, only in the root or /docs folder.

To keep things simple and clean, we’re going to put our static site in a /docs folder in the main branch.

In your Github repository settings, navigate to the Pages section. It should look something like this:

In the “Source” section there’s a dropdown that currently says “None”. Instead of None, choose the main branch and then the /docs folder, as shown below.

Click “Save” and the page will reload and tell you that your site is ready to be served.

Configure SvelteKit for Github Pages

Now we have to tell SvelteKit that we want our static site to go in the /docs folder.

First, we need to install the SvelteKit static adapter which will output our app as a static set of files instead of a dynamic app:

npm install @sveltejs/adapter-static --save-dev

(You can also run npm uninstall @sveltejs/adapter-auto --save-dev to remove the unnecessary auto adapter from your package if you want.)

Edit svelte.config.js to use the static adapter as shown below:

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

const dev = "production" === "development";

/** @type {import(""@sveltejs/kit").Config} */
const config = {
    kit: {
        adapter: adapter({
            pages: "docs",
            assets: "docs"
        }),
        paths: {
            // change below to your repo name
            base: dev ? """ : "/your-repo-name",
        },
        // hydrate the <div id="svelte"> element in src/app.html
        target: "#svelte"
    }
};

export default config;

There are a few things we changed from the default sveltekit config file. We imported adapter-static instead of adapter-auto at the top of the file. We also configured the adapter to use the docs folder as the output target for both our site’s pages as well as static assets like stylesheets, images, and so on.

And finally we also added a paths configuration option which tells SvelteKit the URL path of the SvelteKit site. By default, Github Pages will host your static site at username.github.io/your-repo-name. So we need to configure SvelteKit so that it knows its URLs should fall under /your-repo-name when hosted on Github Pages, but not when testing our site on our own computers (it’s hosted at localhost:3000/ during testing with npm run dev).

You can run npm run dev again to make sure everything is still working before going to the next step.

Add a blank .nojekyll file in static

To configure Github Pages so that it doesn’t use the Jekyll static site generator (which it does by default), we simply have to create a blank .nojekyll file in the static folder. You can do that any way you like, but here’s how you can do it from the command line:

touch static/.nojekyll && git add static/.nojekyll

Deploy your site on Github Pages

So we have a demo site that runs fine on our computer with npm run dev but we want to deploy it on Github pages. To do that, we use SvelteKit’s build command.

npm run build

This command will create a docs folder if it doesn’t exist and put all the HTML, CSS, and JavaScript files there. It will also delete and recreate the docs folder every time so make sure not to put any other files in there or they might be deleted.

Don’t forget to add the docs folder to your repository:

git add docs

Now if you commit your changes...

git commit -m "add /docs"

...and push them to Github...

git push origin main

Github will automatically deploy your site! In the Github Pages settings you’ll see this right after you push:

If you wait a little bit, eventually that page will look like this:

Click the link to see your new site running with Github Pages!

That is generally the process every time you make a change:

1. npm run build
2. git add docs && git commit
3. git push origin main

Custom Domains for Github Pages

There is one last thing you need to do only if you want to host your SvelteKit site on a custom domain through Github Pages.

First, read about how to set up custom domains on the Github Pages guide here.

The main thing you’ll need in your SvelteKit repository is a CNAME file containing the URL of the site you want:

yourcustomdomain.com

Put this CNAME file in the static directory of your SvelteKit project and you’re good to go!

Addendum: Getting HTTP, HTTPS, and WWW working with custom domains on Github

This isn’t a SvelteKit-specific thing but it’s a little confusing how to properly configure DNS for Github Pages so that all the following custom domain URLs will work:

example.com
www.example.com
http://example.com
http://www.example.com
https://example.com
https://www.example.com

To make all those work, it’s pretty simple. Just add “A Records” pointing toward Github’s IP addresses, as well as a “CNAME Record” for www pointed at username.github.io:

You should also choose “Enforce HTTPS” from the Github Pages settings page. With this setup, every URL from the list above will automatically go to https://example.com.