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)
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:
And it is automated I can also send over the github pipeline script if you want it.
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.
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.
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!
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.
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 :)