Deploying Your SvelteKit App to GitHub Pages with a Custom Domain (Ditch GoDaddy for Porkbun)

Manuel AZ — Tue, 17 Dec 2024 17:45:51 +0000

It's 2023, I've been laid off, and I need a portfolio site to prove I know things. I sketch out a design in Figma but get sidetracked building a sauna in my basement. Spoiler: the sauna gets finished before the site.
Fast forward - new job secured, but the portfolio mocks gather dust. Eight months later, I finally finish the site using Svelte, the shiny new framework with syntax I loved. But deploying it? Enter GoDaddy. Hours of wrestling with DNS settings and learning I'd need to buy and configure an SSL certificate left me frustrated. That's when I found Porkbun - transparent pricing, free SSL, and a painless setup.
Now, let me show you how to get your Svelte app live, step by step, without the headaches I endured.

Step 1: Install the Static Adapter

SvelteKit offers a variety of adapters tailored to different deployment setups - Node.js servers, serverless platforms, edge functions, and more. The adapter you choose determines how your app gets deployed. For GitHub Pages, we'll use the @sveltejs/adapter-static, which is ideal for static site hosting.
Install it as a development dependency:

pnpm add -D @sveltejs/adapter-static

With this adapter, your app is pre-rendered into static files during the build process, ready to go live. Simple and effective!

Step 2: Configure Static Adapter

Start by importing the newly installed package into your svelte.config.js file. Next, add the default configuration provided below. Feel free to tweak it to suit your needs, and refer to the adapter-static documentation for more details.

import adapter from '@sveltejs/adapter-static';
import { sveltePreprocess } from 'svelte-preprocess';

export default {
 preprocess: sveltePreprocess({ ...sveltePreprocess() }),
 kit: {
  adapter: adapter({
   // default options are shown. On some platforms
   // these options are set automatically - see below
   pages: 'build',
   assets: 'build',
   fallback: 'index.html',
   precompress: false,
   strict: true
  })
 },
};

Finally, run your build command and confirm that your project's output is in the build folder:

pnpm build

Step 3: Hands-Free Deployment with GitHub Actions

Add a .github/workflows folder to the root of your project, and inside it, create a deploy.yml file. This file tells GitHub Actions how to handle your app’s deployment. Here’s an example configuration—be sure to adjust it for the package manager you’re using:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 8

      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: pnpm run build

      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          # This should match the `pages` option in your adapter-static configuration
          path: 'build/'

  deploy:
    needs: build_site
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

With this in place, every time you push changes to the main branch, GitHub will automatically deploy your app. You can verify the deployment by visiting your GitHub Pages default URL, which is typically:

https://<your-github-username>.github.io/<your-repo-name>

Step 4: Porkbun Over GoDaddy — DNS Setup Made Easy

Head over to Porkbun and purchase your domain. Feel free to add any extras you want — I went with the most basic option, which cost $38.55.

Next, go to your Domain Management page. Hover over the row for your domain, and you’ll see the DNS text appear — click it to open the settings modal (see the screenshot for reference).

With the modal open, scroll down to the Quick DNS Config section and select GitHub. This will automatically populate the necessary DNS records for your deployment, saving you possibly an hour of setup and sparing you the headache of worrying about SSL certificate configuration — unlike GoDaddy.

Step 5: Github page Settings

The last step is to update your GitHub Pages settings and point them to your custom domain. Head to the settings page for your repository and navigate to the Pages section. Make sure the deploy source is set to GitHub Actions (since that’s how we’ve set up deployment).

Next, paste your custom domain into the Custom Domain input field and save the changes. GitHub will start verifying your domain and setting up the SSL certificate. This might take some time, and you may need to refresh or retry for the Enforce HTTPS checkbox to become available.

Once everything is verified, your app will be live at your custom domain. Congratulations — you’ve officially deployed your Svelte app! 🎉