Publishing GitHub Pages with Svelte

In previous lessons, we’ve learned how to use GitHub to run code with GitHub Actions. There is another amazing feature of GitHub I wanted to share with you: Pages.

If you build your website as static files from a repository, GitHub can automatically create a website with them — for free! Pages are often used to host library documentation, but they can be anything you want!

In this lesson, I am going to show you how to use the setup-sda library we’ve been using in many previous projects to (very) quickly publish your data projects on GitHub.

If you haven’t done so, I suggest you check the Svelte lesson, since that’s what we’re going to use to build our website.

Setup

Create a new folder and open it in VS Code. Then run this command to install and set up everything we need with setup-sda:

• deno -A jsr:@nshiab/setup-sda --svelte --example --pages --git

The library sets up a sda folder to work with the Simple Data Analysis library, as we saw in the section 3. The SDA library 🤓. But the options add a few things:

• --svelte will also set up a Svelte project
• --example will add data and code to show a full project example
• --pages will add a GitHub workflow (as we saw in the previous lesson) and tweak some configuration files
• --git will initialize and make the first commit once all files are in.

Once the command has run, you can execute deno task dev, open the local URL, and you should see an example website! Feel free to explore the code and the page.

Creating a repository

It’s now time to head over to GitHub and create a new repository. Give it a name (my-website for example), make it public, and there is no need for a README or .gitignore since setup-sda took care of all that.

Now copy the commands to push an existing repository from the command line.

Then paste and run them in your terminal.

Now, if you refresh your repository page, you’ll see your code!

Enabling GitHub Pages

Now it’s time to enable GitHub Pages on the repository!

Click on your repository Settings, then on Pages in the left sidebar. Then select GitHub Actions for the Build and deployment source.

Now, go check your Actions tab. We have one workflow to build and deploy our website. But it failed because GitHub Pages was not enabled when we did our first push. Click on it.

Click on Rerun jobs and wait for a few seconds.

And now it works! GitHub Actions successfully did the two jobs: building our website and then publishing it! You now have a link to your website!

If you click on the link, you’ll see your website live!

You can also retrieve the link to the website in your settings.

Updating main

Now, let’s do something fun. Let’s update the code on the main branch and push it to GitHub.

In src/routes/+page.svelte, I changed <h2>Climate change</h2> to <h2>Climate change example</h2>. I know, I’m going crazy.

Let’s commit and push this to GitHub:

• git add -A
• git commit -m "Update"
• git push

If you check your Actions tab, you’ll see the workflow being triggered again by your push. Every time you update the main branch, your site will be rebuilt and republished! Magic! 🧙

PS: I have two Update messages in the screenshot because I messed up. But you should have just one!

And after a few seconds, your website will be updated!

With this setup, you can focus on your code, work on branches, see your website locally as you work on it, and when happy, make a pull request to merge into main.

Once merged, your website will automatically be republished! 🤩

But… how?

That was easy, wasn’t it? 🥳 To make it work, there are a few things setup-sda did for us.

In the svelte.config.js file, it set up a paths.base to make sure Svelte knows that the website address will start with something like https://your-username.github.io/my-website/. This information will be passed with an environment variable in the GitHub workflow.

import adapter from "@sveltejs/adapter-static";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import process from "node:process";
 
/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter(),
    paths: {
      base: process.argv.includes("dev") ? "" : process.env.BASE_PATH,
    },
  },
};
 
export default config;

The next big thing is the GitHub Actions workflow, of course.

In .github/workflows/deploy.yml, many things are happening. If you want to fully understand them, check the GitHub Actions lesson.

But to summarize, there are two jobs here that are triggered when there’s a push on main:

• build_site, which builds the website by passing an environment variable github.event.repository.name (used in our svelte.config.js, as covered just above)
• deploy, which publishes the files created by build_site.

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 Deno
        uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x
 
      - name: Install dependencies
        run: deno install
 
      - name: build
        env:
          BASE_PATH: "/${{ github.event.repository.name }}"
        run: deno task build
 
      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          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

Conclusion

I hope you’ll find this setup useful. I created setup-sda to make my life easier. With it, I can crunch and analyze data with the Simple Data Analysis library in the sda folder and then work on interactive visualizations in the src folder with Svelte. It’s the best of both worlds!

And with GitHub Pages, I can easily share my findings with the world. Now that you’ve completed this lesson, you can too!

Let me know if you use it! 🤗