How I use Vue.js on GitHub Pages

tiim profile image Tim Bachmann ใƒป3 min read

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

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 โ™ฅ

Posted on by:

tiim profile

Tim Bachmann


I'm a swimmer, swim coach and CS student in Switzerland


Editor guide

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).


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

TravisCI Github Pages Deployment


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.

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


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.


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


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.


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


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.


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.


I did the same thing... But with react. Only had to compromise with using hash router. Automated with Makefile though. Kept the data in yaml files in a separate branch.


Yeah you have to do this in Vue too, but that's the standard setting in the vue cli so I didn't mention it here.


Great article ! And very helpful
Thanks !


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! ๐Ÿค˜


I'm glad I could help ๐Ÿ‘


Awesome, thanks!


Hi, but why does it fail to work when we set custom domain?


I seem to fail at getting it to work.

I see my page without content. But it isn't pulling in the data via an API on a different server.


Take a look at the error(s) in the dev console. Maybe they are helpful :)