Automatically build and deploy a Vue.js app with GitHub Pages

Editor’s note: This post was updated on 5 November 2021 to reflect updates to Vue 3 and improve the tutorial based on comments received since publication. 

Vue.js was created by Evan You and is continuously maintained and updated by 250-plus community members. It is a very progressive framework for building user interfaces, consisting of an approachable core library that focuses only on the view layer and an ecosystem of supporting libraries that help you tackle the complexity of building larger single-page applications.

In this post, you will be introduced to an easy way to build Vue applications and how to deploy them with GitHub Pages.

Before we start

This post is suited for frontend developers that use Vue.js at any level, so being conversant with beginner concepts and installation processes is not assumed. There are a few prerequisites you should already have before you start using Vue CLI 3 through this article.

First and foremost, you’ll need Node.js ≥10.x installed. You can verify whether you already do by running the following command in your terminal:

node -v

You’ll also need:

• npm ≥ v6.7 installed
• A code editor — I highly recommend Visual Studio Code
• General knowledge about using Git
• Vue’s latest version installed globally on your machine
• Vue CLI ≥ v3.0 installed on your machine

To install the latest Vue CLI version, run the command:

npm uninstall -g vue-cli

Then, install the new one:

npm install -g @vue/cli

Alternatively, you could:

• Download a Vue start project here
• Unzip the downloaded project
• Navigate into the unzipped file and run the command to keep all the dependencies up to date:

npm install

What is GitHub Pages?

GitHub Pages is a static site hosting service that deploys your static apps straight from their GitHub repository. You can have GitHub Pages set up for yourself as a user (mostly useful for personal branding assets like portfolios), which lets you deploy to yourGitHubUsername.github.io.

To do this, you have to create a new repository on GitHub and call it:

<Your username>.github.io

After you save the repository, it automatically creates a GitHub Page for you using the HTML at the root of the project. You can also set up GitHub Pages for any new or existing repositories you have on GitHub.

In this post, we will create a Vue.js project and then deploy it to GitHub Pages.

Vue project setup

Let’s use the Vue GUI to create a new project. If you have followed this post from the start and already have the Vue canvas, you can still create a new project to gain experience using the GUI.

On your machine, navigate to a preferred location and open up your terminal. Run the command below:

vue ui

You will be redirected to a remote server live on your default browser where you can create and manage a Vue project. Your browser will look like this:

When you click Create and select the location of your choice, it begins setting up the new project. In the first details page, enter your project name and leave everything as default, but toggle the Git initialization to Off.

On the preset page, choose the default preset, which has Babel and ESLint, and hit enter. This will take a while and might return an error if you are not running the command as an admin on your machine. If successful, you should see a completed notification, and the logs should look like this:

Now click the Home button in the bottom left, choose the newly created project, and import it into the remote server. Now our app has been created and we can view it in a development environment by running:

npm run serve

To do this, click on the GUI by clicking on Tasks, choosing Serve, and running the serve task.

Now that we have successfully built a sample Vue application, you can click on Open app to view the Vue application in localhost.

Setting up GitHub

The first thing to do is to create a GitHub repository with the new project (this would normally have been created for us during the scaffolding stage, but we disabled it).

First, go to your GitHub account and create a new repository, and then in VS Code, where the project is located in your local machine, open a new terminal and set it up for Git with this command:

git init
git remote add origin https://github.com/your username/github project name.git

Replace the keywords with your own project credentials. VS Code lets you stage, commit, and push your changes easily within the app, so let’s use that. Click on the Source Control tab at the far left in VS Code and commit your changes. After that is successful, you can then click the Download button close to the footer of the VS Code app.

Deploying to GitHub Pages with a Node.js script

The first thing you’ll have to do is create a vue.config.js file in the root directory of your Vue project and copy the code below into it:

module.exports = {
  publicPath: '/project name/'
}

Now commit and push the changes to the origin master branch. For our deployment, we’ll use a Node.js script written by Roland Doda, which enables automatic deployment and is based on the execa package.

Create a Scripts folder in your app’s root folder and inside it create a gh-pages-deploy.js file. Paste the code block below inside:

/* eslint-disable no-console */
const execa = require("execa");
const fs = require("fs");
(async () => {
  try {
    await execa("git", ["checkout", "--orphan", "gh-pages"]);
    // eslint-disable-next-line no-console
    console.log("Building started...");
    await execa("npm", ["run", "build"]);
    // Understand if it's dist or build folder
    const folderName = fs.existsSync("dist") ? "dist" : "build";
    await execa("git", ["--work-tree", folderName, "add", "--all"]);
    await execa("git", ["--work-tree", folderName, "commit", "-m", "gh-pages"]);
    console.log("Pushing to gh-pages...");
    await execa("git", ["push", "origin", "HEAD:gh-pages", "--force"]);
    await execa("rm", ["-r", folderName]);
    await execa("git", ["checkout", "-f", "master"]);
    await execa("git", ["branch", "-D", "gh-pages"]);
    console.log("Successfully deployed, check your settings");
  } catch (e) {
    // eslint-disable-next-line no-console
    console.log(e.message);
    process.exit(1);
  }
})();

These commands above simply automate the whole process of:

• Creating a GitHub Pages branch in your repository
• Building out your Vue application for production
• Committing and pushing the changes of the built dist file to Pages
• Deleting and totally removing the GitHub Pages branch after the build has been picked and deployed. This is so that you can run the command again after any new changes without errors

Now open your package.json file and add the execa config to your dev dependencies, like so:

//.json
"devDependencies": {
      "execa": "latest"
    }

Then, down in the scripts section, add this:

//.json
"scripts": {
     "deploy": "node scripts/gh-pages-deploy.js"
    }

Now, to install them and ensure they are up to date, run this command in your terminal:

npm install

We are set to go. To deploy your Vue app with GitHub Pages, simply run this command below:

npm run deploy

This deploys your Vue app to the public and gives you a unique link. Open up that project on GitHub and click on Settings.

Your Vue app is live!

Conclusion

In this article, we walked through creating a Vue application with the Vue UI tool and hosting it on GitHub Pages by automating the bulk of the process using an execa Node.js script. I hope this helps you with your Vue.js projects — stay safe and keep hacking!