Tim Bachmann

Posted on May 4, 2019

How I use Vue.js on GitHub Pages

#github #pages #vue #javascript

I recently read the Article Serving Vue.js apps on GitHub Pages and it inspired me to write about what I'm doing differently.

If you want to see an example of this method in action, go check out my personal website on GitHub

I won't be explaining how to setup a Vue project. If you're looking for a Tutorial on that go check out the awesome Vue.js Guide.

So you have setup your awesome Vue project and want to host it on GitHub Pages. The way Muhammad explained it you would build the project using npm run build, commit the dist/ folder along with your source files and point GitHub to the dist folder. This might get quite messy because you either have commit messages with the sole purpose of uploading the dist folder or you commit the code changes at the same time which makes it hard to find the relevant changes if you ever want to look at your commits again.

So what can you do about this?

Git to the rescue, let's use a branch that contains all the build files.

Step 1 - keeping our working branch clean 🛀

To make sure that the branch we are working from stays clean of any build files we are gonna add a .gitignore file to the root.

# .gitignore
dist/

Step 2 - adding a second branch 🌳

We are not goint to branch off master like how we would do it if we were to modify our code with the intention to merge it back to the main branch. Instead we are gonna create a squeaky clean new branch that will only ever hold the dist files. After all we will not ever need to merge these two branches together.

We do this by creating a new git repository inside the dist folder:

cd dist/
git init
git add .
git commit -m 'Deploying my awesome vue app'

Step 3 - deploying 🚚

We are gonna force push our new git repository to a branch on GitHub. This might go against git best practices but since we won't ever checkout this branch we don't have to worry about that.

git push -f git@github.com:<username>/<repo>.git <branch>

⚠️ Make sure you double or tripple check your destination branch! You don't want to accidentally overwrite your working branch. Using the branch gh-pages will most likely be a good idea.

Step 4 - pointing GitHub to the right place 👈

Now we are almost done. The only thing left is telling GitHub where our assets live.

Go to your repo, on the top right navigate to Settings and scroll down to GitHub pages. Enable it and set your source branch to the branch you force pushed to, for example gh-pages.

Step 5 - automating everything 😴

If you don't mind doing this whole process (Step 2 and 3) every time you want to deploy you can stop now. If you're as lazy as me, here is the script I use to deploy with one command:

# deploy.sh

#!/usr/bin/env sh

# abort on errors
set -e

# build
echo Linting..
npm run lint
echo Building. this may take a minute...
npm run build

# navigate into the build output directory
cd dist

# if you are deploying to a custom domain
# echo 'example.com' > CNAME

echo Deploying..
git init
git add -A
git commit -m 'deploy'

# deploy
git push -f git@github.com:<username>/<repo>.git <branch>

cd -

If your on windows look into the Windows Subsystem for Linus (WSL) it will be worth it.

If you are still reading, thank you very much. This is actually my first article and I'm really happy to hear about any opinions and criticisms.
Happy Coding ♥

Top comments (18)

Ian Kirker • May 5 '19

For the next level of automation, if you set up deploy keys and Travis CI, you can encrypt the private key using Travis’s tools, check the encrypted file into the repo, and then have this script run on Travis every time the master branch is changed (along with a snippet to decrypt the key for use).

Tim Bachmann • May 5 '19

Yes exactly!
Or even better use the functionality that's already built into Travis CI:

TravisCI Github Pages Deployment

Ian Kirker • May 5 '19

Oh, neat, thanks, I hadn’t seen that!

We might still have to use the keys, for organisational repositories, but it’s definitely something I’ll look at.

Tim Bachmann • May 5 '19

Yeah it's both pretty much the same so no real drawbacks either way.

Pablo Calvo • Apr 13 '20

Hey man,

Great post. Really made the trick. To automate the process, i decided to have develop as the dev code branch and then push the dist to master where bitbucket picks it up.

And then using github actions I run this script:

cd dist
git init
git remote add origin git@github.com:coffeestainio/coffeestainio.github.io.git
git add .
git commit -m 'new deploy'
git push --set-upstream origin master -f

And it is automated I can also send over the github pipeline script if you want it.

Akinhwan • May 18 '19

how do you serve images? I'm getting confused between /static and /assets. the href I set in the html part of my component works correctly, but in the css section the url i set for background image is not finding in the same path

Tim Bachmann • May 18 '19

The static/ folder is for files like images and css that should not be touched by webpack where as files in the assets/ directory will be processed.

M. Stevens • May 5 '19

I have a question, what would be the benefits of turning your personal site into a VueJS app as opposed to React?

Phiter Fernandes • May 5 '19

I would say the main advantage is using Vue instead of React. It's all about your preference in this case, but I would always go with Vue.

Tim Bachmann • May 5 '19

I don't think there are any clear advantages for any of the two. It comes down to preference.

For me personally I really like the structure of Vue because it still kinda seperates html from javascript. I'm not a big fan af jsx.

Enrique Melero • May 5 '19

Great article ! And very helpful
Thanks !

Pieter Montoulieu • May 4 '19

Thanks for this dude!
I just recently migrated my personal site to a GitHub user page on master and couldn't figure out a way to get it load properly! 🤘