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 email@example.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
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 firstname.lastname@example.org:<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 (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
masterbranch is changed (along with a snippet to decrypt the key for use).
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.
Great post. Really made the trick. To automate the process, i decided to have develop as the dev code branch and then push the
distto 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.
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 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 don't think there are any clear advantages for any of the two. It comes down to preference.
Great article ! And very helpful
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 👍
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 :)