Deploying Vue Apps to Github Pages

Photo by SpaceX on Unsplash

Call me impatient, but I think it should be just as easy to deploy your app online as it is to share this article.

The good news is, these days, that’s nearly true. However, while the official Vue deployment documentation is decent, it does assume prior knowledge in some areas. In this article, I’ll attempt to fill in those gaps and provide a clearer picture of how it all comes together.

Our goal will be to build a simple hello-world Vue app, deploy it to Github Pages (a great solution for showcasing prototypes and simple front-end apps that don’t require a server), and establish a simple deployment workflow so you can continue to iterate and go live with your changes over time.

Note 1: I’m using the Mac terminal, Visual Studio Code, and yarn, as my package manager. The steps are nearly the same if you’re using npm.

Note 2: For ease, my app name and repo name will be identical: hello-world

Note 3: I won’t be covering how to actually write Vue code. For that, check out the official docs.

Step 1: Create a Boilerplate Vue App

Open the terminal and type the following:

vue create hello-world

For expediency, I’ll be selecting the default preset, though you may elect to manually select features.

If you see an error, you likely need to install vue/cli.

Step 2: Create a New Github Repository

Note: The repo must be set to Public in order to publish to Github Pages.

Once you’ve created the repo, leave the tab open and return to the terminal.

Step 3: Update the Public Path of the Vue App

cd hello-world
code .

If you don’t have the code . command or you’re using a different IDE than Visual Studio Code, simply open the Vue app.

We’ll end up adding two new files at the root of our Vue App. We’ll start with:

touch vue.config.js

Open the newly created config file and copy/paste the following (this code snippet is from the official Vue deployment documentation).

module.exports = {
    publicPath: process.env.NODE_ENV === 'production'
    ? '/hello-world/'
    : '/'
}

Alternatively, if you prefer to use the Vue CLI interface, you can skip creating a separate config file altogether.

vue ui

Step 4: Write a Shell Script for Deployment

This is the second and last file we will be adding at the root of our app.

touch deploy.sh

Open the deploy file and copy/paste the following (this code snippet is a slightly modified version of the official Vue deployment documentation). Don’t forget to insert your own Github account username.

#!/usr/bin/env sh
# abort on errors
set -e
# build
yarn run build
# navigate into the build output directory
cd dist
# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
git push -f git@github.com:username/hello-world.git master:gh-pages
cd -

Note 1: If you’re using npm, swap out yarn.

Note 2: We’ll be deploying to a specific repo, but the official docs contain other options as well.

Lastly, make sure your script is executable!

chmod +x deploy.sh

Step 5: Create a Deployment Script

Open the package.json file at the root of the Vue app and include the following deploy script in bold.

"scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint",
    "deploy": "sh deploy.sh"
},

Step 6: Push to Github

git remote add origin https://github.com/username/hello-world.git

git push -u origin master

Step 7: Try to Deploy

yarn deploy

If you see the error “Permission denied (publickey). fatal: Could not read from remote repository,” then you need to set up an SSH key and add it to your Github account. All the docs you’ll need are linked below. Don’t worry, they’re not long and mostly consist of copying and pasting various commands.

• Generating a new SSH key
• Adding your SSH key to the ssh-agent
• Adding a new SSH key to your GitHub account

Step 8: Update Github Settings

When you deploy, you may see this in the terminal: “remote: Create a pull request for ‘gh-pages’ on GitHub.”

Go back to the Github tab we left open and refresh. You should now see your project files. Let’s switch our branch to gh-pages.

Now go into Settings, scroll down and and ensure gh-pages is listed as the Source.

Step 9: View the Results

Our hello-world app should now be viewable at:

https://username.github.io/hello-world/

Step 10: Test the Deployment Workflow

Note: The master branch will act as our repo for version control. The gh-pages branch will contain the compiled build code that Github Pages uses to display our app.

1. Make some changes to the app, replacing the boilerplate code.
2. Commit those changes to the master branch. Note: This first commit will include the two files we added.
3. Deploy, using the script we created in Step 5.
4. Go back to the URL and refresh. You should see your changes. Note: it may take a few moments to update.
5. Share your app with the world!

And we’re done! Congrats :D

If you have any thoughts or suggestions, let me know in the comments.