Concise guide to continuous integration for a static site on GitHub Pages with a free domain
I had a dream, that one day, my single page applications (SPA) will live free of (hosting) hostage, where they are no longer manually deployed, and have proper (domain) names. Not until this day, I have found the way plowing through my pet project, and I am going to share it with you in a hands-on, concise way, so your SPA too may be set free.
Assume you already have a project repo, we’d need to take care of a few things:
- a domain name
- a place to host your code and the deployed web app
- a service to auto-deploy your web app whenever you commit new code
We’ll go through these step by step. Note that we’ll be using yarn as package manager.
A Name for Everyone
First, your SPA needs a name, for free, which you may obtain at freenom, whose credit card free registration is very attractive. You may reserve a domain name up to 12 months at a time.
A Home for Developers
Second, your SPA needs a hosting, for free, which you can setup a repo for your codebase at GitHub. Your code would be on master branch and the build will live on the gh-pages branch of the repo. Read this for a git/version control refresher.
Publish Directory to Branch
Before you deploy your SPA, you’d need a build command (e.g., yarn build) in your package.json which would call certain bundler (e.g., webpack) to do its magic and generate your site in a build/dist folder. For a refresher of yarn read this.
Instead of dealing manually with version control of your dist folder, you can use publish-dir npm package to publish a whole folder to a separate branch in a single line.
To install: yarn add -D publish-dir
Then add a line for deployment in your package.json under scripts:
"deploy": "push-dir --dir=dist --branch=gh-pages"Before we try our newfound magical power to deploy, let’s set up your custom domain name in a CNAME file with a single line: your naked domain name (without the www subdomain and the protocol). This file should sit in your static or public folder so it gets copied to the dist folder as you build.
Commit now so that your repo is clean:
git add -A && git commit -m "add CNAME, push-dir, and deploy command"Now you can try the semi-automatic deploy to gh-pages by running yarn deploy.
Set up your website on GitHub
Now you should see a new gh-page branch on your GitHub repo. Go to the repo’s settings, verify that GitHub Pages is setup properly on the gh-page branch, and that your custom domain is in use. You can also enforce https by ticking the checkbox. Now we are ready for the full automatic deploy.
CI to the Rescue
Setup a Travis-CI account, for free, with your GitHub login. You will then see a list of your repos. Choose the repo you are working on, and activate it (with a toggle).
Enter the repo’s travis settings page, setup an environment variable called GITHUB_ACCESS_TOKEN which you will obtain from GitHub (here). Choose the public_repo permission would be enough if your repo is public. Copy the token and set it in the travis page.
The Final Step
Our final step is setup our git repo so that travis-ci would know what to do when you push code.
Create a .travis.yml with the following:
language: node_js
node_js:
- "8"cache:
directories:
- "node_modules"branches:
only:
- masterinstall:
- yarn
- yarn buildscript:
- echo "Skipping tests"deploy:
provider: pages
skip-cleanup: true
github-token: $GITHUB_ACCESS_TOKEN # Set in travis-ci.org dashboard, marked secure https://docs.travis-ci.com/user/deployment/pages/#Setting-the-GitHub-token
target-branch: gh-pages
local-dir: dist
on:
branch: master
Also, don’t forget to add dist/ to your .gitignore
When you are ready, commit and push:
git add -A && git commit -m "add travis config" && git pushNow watch travis-ci auto-deploys your site each time you push code to your master branch.
May your SPA live long and prosper :)
PS: gh-pages is a similar tool to push-dir, feel free to give it a try and comment below which you like better.
