How to publish a single page application at no cost with GitHub Pages (React, Svelte, etc)
UPDATE 20th May 2023: I no longer use this method and the package gh-pages to deploy my SPA to GitHub Pages, I would recommend using GitHub Actions instead, to deploy your SPA on every push/merge: https://vitejs.dev/guide/static-deploy.html#github-pages
With GitHub Pages, you can create a website and publish it at no cost. This is suitable to show off a project you’ve been working on, your portfolio (for your personal website), or your organisation/company.
Regular static webpages can be deployed easily, or it can just show your repository’s README.md .
So how can we take a single page application we made (with React, Svelte, etc) and deploy that to our GitHub Pages? It’s pretty simple.
Keep in mind that if your website utilizes a back-end, it may have to be hosted elsewhere.
Step 1: Your project repository!
If you are making a personal website, make sure to name your repository like yourusername.github.io . Apparently, it’s another one of GitHub’s “secrets”, so that the website will not be under a path / , but instead just yourusername.github.io .
If your repository name isn’t like the above, your website can be accessed under yourusername.github.io/repository-name .
Also, unless you have a Pro GitHub account, your private repositories cannot enable GitHub Pages. So bear that in mind if your repository contains any sensitive information.
Step 2: Install the gh-pages package
The npm package gh-pages is necessary to deploy your app to GitHub Pages. So just install it in your project’s devDependencies :
npm i -D gh-pagesStep 3: Your scripts
Go to package.json and add the following scripts:
"predeploy": "npm run build","deploy": "gh-pages -d build"
"predeploy" has to point to the script that builds a production ready, optimized version of your app. As for the "deploy" script, the folder name after the -d flag is what gh-pages is going to deploy. In my case, it’s called build .
To sum it up, "predeploy" will take your code and build the optimized version to a build folder. The "deploy" script will take the contents of that folder and deploy it to GitHub Pages. So make sure to point to the right scripts and folders!
Step 4: Build and deploy
Just run the "deploy" script by doing npm run deploy in the terminal. The "predeploy" script will be called first before sending the build to GitHub.
When you see the terminal say Published , you can go ahead and check your repository’s branches. You will see another branch called gh-pages . This branch contains the production build of your app.
To change the branch that your app is deployed to, you can add the -b flag to your script, followed by the branch name of your choice:
"deploy": "gh-pages -d build -b branchname"Step 5: Enable GitHub Pages
If your repository name is like yourusername.github.io , your GitHub Pages will be enabled automatically. When you enter the page it will just display your repository’s README.md as shown above. But, we want it to display our app we just deployed. So let’s do it now:
Go to your repository settings, and click Pages:
From this page, you can select whichever branch and folder to deploy. Make sure to select the branch that the script just deployed to, in my case, it would be gh-pages . Click Save and GitHub Actions will start deploying the app.
After that is done, when you go to your URL, your app will be displayed.
And there we go! Your app is now deployed and public. It can be accessed by whoever enters your URL.
Tip: Routing
For routing between multiple pages, a Hash Router should be used. Yes, your URLs will have a # in between, but if not used, the other pages cannot be accessed directly.
For React, you may import HashRouter from react-router-dom , and for Svelte, you may just import the Router from svelte-spa-router .
Tip: favicons
I added a favicon to my website. But when published on GitHub Pages, it’s nowhere to be seen.
The way favicons are linked are different when the app is published on GitHub Pages. Here is one that worked for me:
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico?" />The question mark (?) at the end is what is needed for the favicon to be able to show up. Also, make sure there is no slash / at the beginning.
Conclusion
That was how you can publish your own single page application with GitHub Pages. In all honesty, it is pretty simple to do. Thank you for reading, I hope this helps you to build your own website, or a website to show off your projects.
Feel free to check out my website and its source code.
