This a little tutorial to create a PWA App with Sapper, and deploy with GitHub Pages.

First, what is a PWA App?

To understand what this mean, I created a simple web app to divide the count of a dinner (for eg.) between friends or family. Is in Spanish but is easy to understand.

La Cuenta

This PWA is available to "install" in you mobile OS to acces directly like anyone other app installed with Play Store (for Android eg.)

Before continuing with this tutorial, can your app be deployed with GitHub pages?

GitHub pages only accepts static content, so your Sapper application must be exported to static files before being deployed, so read the Sapper exporting documentation to find out if your app can be exported and hosted on GitHub Pages.

So, after this, we can start!

Step 1

First of all, basic, install Sapper

After this, you can start to create the logic and UI for you proyect.

Step 2

Assuming your project is ready and functional, or at least ready to be tested live, you have to create a new GitHub Repo.

Step 3

Instal via npm or your favorite package manager gh-pages package.

npm i gh-pages

After installed, create a folder named script in your app root structure.

And then, into this folder, create a .js file, I named it gh-pages. Into this js file, copy the following code:

const ghpages = require('gh-pages');

ghpages.publish(
    '__sapper__/export/<your-app-name>',
    {
        branch: 'master',
        repo: 'https://github.com/<your-github-username>/<your-repo-name>.git',
        user: {
            name: '<your-github-username>',
            email: '<your-github-email>'
        }
    },
    () => {
        console.log('Deploy Complete!')
    }
)

Note that in the branch option the master branch is placed. Read on to find out why :D

Step 4

Go to your Sapper server.js file. Add the following lines:

import sirv from 'sirv';
import polka from 'polka';
import compression from 'compression';
import * as sapper from '@sapper/server';

const { PORT, NODE_ENV } = process.env;
const dev = NODE_ENV === 'development';

const url = dev ? '/' : '<your-app-name>'; // <<-

polka()
    .use(
        url, // <<-
        compression({ threshold: 0 }),
        sirv('static', { dev }),
        sapper.middleware()
    )
    .listen(PORT, err => {
        if (err) console.log('error', err);
    });

This means that while we develop and test our app on localhost, the app uses the root directory. But when it's deployed, use / <your-app-name>

Step 5

Now we are going to edit the package.json file adding the following scripts:

"deploy": "npm run export && node ./scripts/gh-pages.js"

And replace export script with the following:

"export": "sapper export --basepath <your-app-name> --legacy"

The reason of everything:

This will make when we run npm run deploy, Sapper will run npm run export to export our application under a folder with our app name, and then run the gh-pages.js file that will deploy this folder in the master branch of our GitHub Repo.

Step 6

Create branch into your proyect with the command git branch <your-branch-name>. And git checkout <your-branch-name>.

Now you can commit and push your changes:

git add .
git commit -m "a commit message"
git push -u origin <your-branch-name>

Now you have a branch <your-branch-name> with the Sapper proyect and the master branch is for deploy the exported proyect and link with your GitHub Page (in the next step).

Step 7

Run the script npm run deploy and wait to Sapper export your proyect. When everything is finished you will see the message configured in gh-pages.js

Deploy Complete!

Step 8

Go to GitHub Repo, and click in Settings. Scroll to GitHub Pages

And select master branch, the first option.

After a few minutes, you can access to you PWA App in your-username.github.io/your-app-name

You can audit your page with LightHouse to check that everything is in order:

Don't forget to have your manifest.json file updated!

You can check my app repository if it helps

I hope everything is understood, if you can't comment below 😀

Greetings!