In this article, I’ll be showing how to take the standard Vue Webpack template and modifying it to deploy to GitHub pages with ease.
To start with, we’ll assume that you have Vue CLI installed. If you don’t, please go here and follow the instructions, then return to complete the rest of the article.
Setting Up Our Project
First off, we need to setup a new project to work in. We can do this using the following:
vue init webpack git-deploy-template
Once this is done, we’re ready to setup our deployment script.
Add Our Deployment Script
For deploying our GitHub pages branch, we will be adding a package to our
package.json using the NPM command. The package we will be adding is called ‘push-dir’ and we can add it with the following:
npm install --save-dev push-dir
Once we have ran this command and the package is installed, we can add a new script to our
package.json file. Open the file now in your favourite editor, which obviously it Notepad++. Now add a key to the scripts section
deploy with the following value:
npm run build; push-dir --dir=dist --branch=gh-pages --cleanup
Checkout the push-dir docs for information on the flags used here. The example above is setup with the most sensible flags enabled however you are free to customize as you please. One flag I will mention here though is
--allow-unclean , which as you might have guessed, allows the
gh-pages branch to be committed, even if the current project branch contains uncommitted changes.
You can swap the
gh-pages branch name for whichever branch you are deploying to. Now we can just run
npm run deploy and it will automatically deploy the contents of our
../dist folder to GitHub. If you read the above carefully, you’ll also notice that our
deploy script automatically calls the
build script first, so there’s no need to build the project first.
From here, we can push a user or organization page and everything will work as it should. The problem will arise when we are setting up a project page as, by default, Webpack will automatically insert all of the asset file names into the page template with a trailing slash. This means that when you go to the page, it will try to resolve the assets from
example.github.io/ rather than
Don’t worry, the problem is easy to resolve and in the next section, we find out how.
Fixing Our Base URL
This is quite a simple problem to fix.
Simply open the
config/index.js file and find the
assetPublicPath entry in the
build section, NOT the
dev section. Change the value of this to the name of you project on GitHub.
Now, when we run the deploy command, it will automatically prefix our asset URLs with the project name, thus enabling the Vue site to resolve all of the assets correctly.
You may not even have to do this at all, as I have now submitted this as a PR to the official Vue CLI Webpack template, which will give you the option to have the deploy script, when installing the template using the standard
vue init webpack <project-name> command.
I’ll keep you updated on the PR, but feel free to head over to GitHub and checkout/comment on the PR. If you want to use the functionality now for yourself, you can use my temporary fork using the collowing:
vue init codetheorist/webpack
The above command will give you the option to set-up a deployment script based on the information in this article.
I hope you’ve found the information in the article useful, let me know in the comments if you have any issues.
Thanks for reading, see you soon.