How to deploy SvelteKit App to Github Pages on Main Branch

If you're new to SvelteKit or GitHub Pages, the official docs might leave you confused. They left me stuck for hours.

The docs skip key steps like GitHub Pages folder structure—crucial if you want a working deploy.

Here’s my way to deploy SvelteKit site to the main branch with zero CSS/JS loading issues.

Install SvelteKit's static adapter

First, run this command on your terminal to install SvelteKit’s static adapter :

npm i -D @sveltejs/adapter-static

Create +layout.js file

Then, add prerender option to the root layout. Create +layout.js in /src/routes/ folder, and paste code below :

export const prerender = true;

This will enable prerendering for all routes under that layout, making them static at build time.

Use the SveteKit's static adapter

Then, add the adapter to the svelte.config.js

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

const dev = process.env.NODE_ENV === 'development'; 

export default {
  kit: {
    adapter: adapter({
      // Set pages and assets to 'docs' to deploy from main branch instead of gh-pages branch
      pages: 'docs',
      assets: 'docs',
      fallback: undefined, // you can set this to index.html if you want
      precompress: false,
      strict: true  // set to 'true' to fail build if some routes can't be prerendered
      }),
    paths: {
      base: dev ? '' : '/your-repo-name'
      }
    }
};

This step is important! You need to set the pages and assets to 'docs' if you want to deploy to the main branch.

Alternative

You can set the pages and assets to 'build' and deploy to gh-pages branch instead, but it requires moving the _app folder inside the build to the root, which is less straightforward for me.

Some tutorials suggest that pushing the build folder directly into the gh-pages branch would work. But without moving the _app folder to the root, makes the css and js not being loaded properly.

Because by default, Github Pages looks for _app folder in the root, not in build folder.

Run the build command

Now, you just need to run the build command :

npm run build

Then you will see new docs folder in the root of your project.

Bypassing Jekyll

To bypass Jekyll, just create .nojekyll file inside the docs folder.

By default, Jekyll will normally ignore files and folders that start with underscores (_). This is important for static sites that don’t use Jekyll but need those files.

From my trial and errors, css and javascript won’t be fetched properly without bypassing jekyll.

Deploying to Github Pages

Before you push the project into the main branch, first you need to set the publishing source on the pages :

1. Go to your project repository

2. Click Settings

3. Under Code and Automation, click Pages

4. Now set the branch to main, and change the folder from /(root) to /docs, and save.

Now you can push the project to the main branch.