Deploy Vue to GitHub pages-the easy way!

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
cd 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 example.github.io/project-name/ .

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.

Plot Twist

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.