An ultimate guide to CICD for your Nuxt.js Application

Prerequisites

To follow along with this tutorial, you will need the following:

• Basic knowledge of JavaScrip and Nuxt
• A CircleCI account
• A GitHub account
• Node installed on your system

What is the CI/CD pipeline?

CI/CD pipeline is a DevOps mechanism for automating the process of software delivery. It involves the continuous automation, integration, and testing phase to delivery and deployment throughout the lifecycle of a software product. CI/CD pipeline helps automate the process of software delivery and enables you to perform build and test automatically. It also helps to improve flexibility with the ability to ship new functionalities faster. By utilizing the CICD pipeline, you can reduce manual errors and provide feedback to software developers, allowing for faster product iteration.

Difference between Continuous Integration, Continuous Delivery & Continuous Deployment

Continuous Integration, Continuous Delivery, and Continuous Deployment are common terms in modern software development practice and the DevOps ecosystem. Often, these terms are used interchangeably and as synonyms. Despite each being part of the software delivery process, each approach differs in its implementation and what they mean to a development team.

• Continuous Integration is a software development practice that involves developers integrating and merging changes to the code base as frequently as possible into the main branch. These changes are validated by creating a build and running automated tests against the build. If these tests fail, the changes are not merged, which provides developers with an opportunity to avoid integration challenges. By implementing continuous Integration, fewer bugs are shipped to production as the issues are detected early, and integration issues are addressed before the release.
• Continuous Delivery extends continuous Integration. It's a software development approach that automatically deploys all code changes to the testing and/or production environment after the changes have been merged. In addition to the automated testing process, there is also an automated release process, which means that developers can deploy changes at any time with the click of a button or after completing the CI process.
• Continuous Deployment takes the process further in contrast to Continuous Delivery. With this approach, product functionalities are delivered through automatic deployment. During each stage in the pipeline, all changes that pass verification are released to production. This process is fully automated, and a new change can only be deployed to production if it passes all tests.
• Continuous Deployment is a great way to accelerate the feedback loop with your customers and relieve pressure on the team. It allows developers to concentrate on building software and see their work go live minutes after they've finished working on it.

CICD pipelines consist of four important stages. Any developer developing a new version of any software should follow the following stages. In the event of a failure at any stage, developers receive feedback notifications.

• Source Stage
• Build Stage
• Test Stage
• Deploy Stage

Setting up your Nuxt.js project

We need to set up a Nuxt.js application and connect it to GitHub to get started. Run the following command to create a new Nuxt.js app:

npx create-nuxt-app nuxt-cicd

After the command, proceed and press Yes. It will prompt an interactive project creation process and ask some questions. Some of these Nuxt CLI implementation questions might change in the future, however, these are the  three important questions and answers for this tutorial:

• Testing Framework?: Select Jest
• Continuous Integration?: Select CircleCI
• Version Control System?: Select Git

After answering all these questions, create-nuxt-app will begin scaffolding the new Nuxt.js application. As soon as the scaffolding is complete, you will need to connect your app to a GitHub repository. Go to your GitHub account and create a new repository. Let the name of your repo be the same as your project, in my case, i.e., nuxt-cicd. After that, connect the project to the GitHub repo you just created. Navigate into the root folder of your Nuxt.js project and run the following command to make an initial commit.

git add .
git commit -m “First Commit”

Then connect your project to the repo by running the following command:

git remote add origin https://github.com/daacode/nuxt-cicd.git
git branch -M main
git push -u origin main

Remember to replace the repository GitHub URL above with yours. With this, your project will be connected to your GitHub repo.

Setting Up Tests with Jest

While setting up our Nuxt project, we chose Jest as our testing framework. The create-nuxt-app has set up what we needed for testing our application (including the packages required and the default test configuration)  along with a jest.config.js file. The test folder is located at the root of the application. Inside the test folder, you will see a default NuxtLogo.spec.js test file with a test for the Nuxt Logo component that simply checks if the component is a Vue instance. Additionally, we will add another test to check if the Nuxt logo components render properly. Replace the NuxtLogos.spec.js file with the following code below:

import { mount, shallowMount } from '@vue/test-utils'
import NuxtLogo from '@/components/NuxtLogo.vue'


describe('NuxtLogo', () => {
  test('is a Vue instance', () => {
    const wrapper = mount(NuxtLogo)
    expect(wrapper.vm).toBeTruthy()
  });

  test("NuxtLogo renders properly", () => {
    const wrapper = shallowMount(NuxtLogo, {})
    expect(wrapper.html()).toMatchSnapshot();
  });
})

After that, save the file and run the tests with the following command:

npm run test

If your test runs successfully, your display screen should be similar to this below:

Setting up the build and deployment script

Next, we need to run the nuxt generate command to create a dist folder at the root of our Nuxt project. This folder will contain a production version of the application to be deployed to a static hosting platform like GitHub Pages. The generated version contains only static files, making it suitable for static hosting

One thing to note about applications deployed to GitHub Pages is that their base URLs are the name of your application's repository. For instance, your URL for the nuxt-cicd application project on GitHub Pages would be https://[YOUR_GITHUB_USERNAME].github.io/nuxt-cicd.

We need to inform our Nuxt application to generate the distribution version and the proper router base when deploying to GitHub Pages. This will cause all of our routes to fail if we don't do it.

The first step is writing a nuxt generate script that specifically targets the deployment to GitHub Pages. Add the following extra script in the script section in your package.json file.

scripts : {
    ...
    "generate:gh-pages": "DEPLOY_ENV=GH_PAGES nuxt generate --fail-on-page-error"
}

In the script above, the generate: gh-pages script sets the DEPLOY_ENV environment variable (which we will reference later in the tutorial) to GH_PAGES (we will use this identity for GitHub Pages) and also add the fail-on-page-error flag that confirms that the build fails if there is a page error.

Then, we need to set our router base inside the nuxt.config.js configuration file. To do that, add the following code just before the module.exports line:

const routerBase = 
    process.env.DEPLOY_ENV === "GH_PAGES"
        ? {
              router: {
              base: "/nuxt-cicd/"
              }
          }
        : {};

We created a routerBase object based on the variable DEPLOY_ENV value in the code above. The routerBase value is set to a router base object targeting GitHub pages if we deploy our application to GitHub pages. Otherwise, the default value should be an empty object. By doing so, we'll ensure that the router base is properly configured for our project. Dont forget to change the base value of: nuxt-cicd if you're using a different slug for your repo.

To complete our configuration, we need to add the following line within the exported object in the nuxt.config.js file:

export default {
    ...routerBase
    ...	
}

Setting up CircleCI deployment Script

As part of setting up the deployment script to deploy to GitHub pages, we need a script that achieves the following:

• To install necessary packages
• To run the tests
• To build the projects
• To deploy to GitHub pages

The first thing we need to do is to create a CircleCI configuration. To do that, create a folder named .circleci in the root folder of your project. Then add a file named config.yml inside the folder.

Installing Packages

Because the node_modules folder isn't pushed to the project repository, we must install the necessary packages for our CircleCI build. Enter the following configuration below inside the config.yml file:

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/node:12.16.0
    steps:
      - checkout
      - run:
          name: update-npm
          command: "sudo npm install -g npm@6"
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: install-packages
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules

As shown in the configuration above, we created a build job that utilizes the Node Docker image available in CircleCI registry. The cimg/node 12.16.0 is a Docker image created by CircleCI to support continuous integration. The tag 12.16.0 implies the version of Node.js will be Node.js v12.16.0; however, your node version might be different.

After that, we check out our code and update npm. Then, we install our dependencies by running the npm install command and creating a cache of our node_modules folder using the save_cache step. Also, we add a restore_cache step to restore our cached assets for use after saving a cache in a previous run.

Running the tests

Next, we need to add a step to run our tests in our configuration. To do that, add another run step :

- run:
    name: test
    command: npm run test

The step will run the npm run test command that we previously ran locally to run our tests using Jest.

Build the project

We will add another step to build our project, as shown below, by running the nuxt generate command.

- run:
    name: build-project
    command: npm run generate:gh-pages

This step above invokes the `generate: gh-pages` script that was designed for deployment to GitHub pages.

- run:
    name: test
    command: npm run test

The step will run the npm run test command that we previously ran locally to run our tests using Jest.

Deploying to GitHub Pages

We need to add the last script for deploying to GitHub pages. Before that, we would need to separate our deploy branch away from the main branch. This separate branch will be maintained exclusively for deployments to GitHub pages. This could be a time-consuming procedure but, fortunately, there is a Node.js package called gh-pages that can help us accomplish that. With this package, we will be able to push our files to a special gh-pages branch on our repository and have them deployed to GitHub Pages.

To do that, add the following deploy steps to your config.yml file:

- run:
    name: Install and configure dependencies
    command: |
        npm install gh-pages --save-dev
        git config user.email "YOUR_EMAIL_ADDRESS"
        git config user.name "YOUR_GITHUB_USERNAME"

- run:
    name: Deploy docs to gh-pages branch
    command: './node_modules/.bin/gh-pages --dotfiles --message "[skip ci] Updates" -d dist'
- store_artifacts:
    path: test-results.xml
    prefix: tests
- store_test_results:
    path: test-results.xml

We install the gh-pages package in the configuration above and set our git configurations for GitHub in our container. Remember to change the values of both user.email and user.name to your own GitHub account details.

In the second step, we use the local installation of our gh-pages package to publish everything in our generated dist folder from the previous build step to our gh-pages branch.

You will notice that we added a few arguments to the gh-pages command. We also assigned a special commit message (prefixed with --message) which contains [skip ci]. This command will instruct CircleCI not to initiate a new build when pushing these contents to the gh-pages branch. Lastly, we assigned --dotfiles to the gh-pages command so that it will ignore all dotfiles.

Here is the complete configuration file:

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/node:12.16.0
    steps:
      - checkout
      - run:
          name: update-npm
          command: "sudo npm install -g npm@6"
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: install-packages
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules

      - run:
          name: test
          command: npm run test

      - run:
          name: build-project
          command: npm run generate:gh-pages
      
      - run:
          name: Install and configure dependencies
          command: |
            npm install gh-pages --save-dev
            git config user.email "youremail@gmail.com"
            git config user.name "daacode"
      
      - run:
          name: Deploy docs to gh-pages branch
          command: './node_modules/.bin/gh-pages --dotfiles --message "[skip ci] Updates" -d dist'
          
      - store_artifacts:
          path: test-results.xml
          prefix: tests
          
      - store_test_results:
          path: test-results.xml

Then commit your changes and push them to the main branch.

Checking Our Deployment

As a first step, we need to connect our project with CircleCI. Go to your CircleCI dashboard (remember we highlighted creating an account at the beginning of this article), and add the project in the Add Project section. Click the Set Up project next to your project. The display should be similar to this below:

Click the Set Up Project to start building the project. Then CircleCI will run the configuration to build, test, and deploy your application. You will notice the build fails. Dont panic; this was expected. To see why the build fails, click on the process tag and inspect every step of the build process. You will discover that the deployment failed at the stage where gh-pages would push our files to the deploy branch. This error occurred because our connection to GitHub, which needed to push our files, was not authenticated.

To establish an authenticated connection with GitHub, we need a deployment key in the form of a private/public SSH key pair that is served in our GitHub account and granted write access.

Setting up authentication to GitHub

Run the following command to create an SSH key pair on our local machine :

ssh-keygen -t rsa -b 4096 -C “ YOUR_GITHUB_EMAIL”

Remember to replace the YOUR_GITHUB_EMAIL with the email address you used for your GitHub account. Then choose a destination name like deploy_key and press Enter to accept the default password of none. Afterward, this should automatically generate a public/private key pair for you at the chosen destination named deploy_key (private key) and deploy_key.pub (public key).

After that, you have to save the private key within CircleCI. Navigate to your CircleCI Pipelines page and click on the button with the cog icon to access the Settings Page.

On the side menu of the Project Setting Page, scroll down and click SSH Keys:

It will prompt a modal box to Add an SSH Key:

The form has two input fields. Enter "github.com" as the hostname, and paste the contents of your "private key()" into the private key field (this was the private key we generated earlier). Then click ADD SSH Key to add the key. Perhaps if you have any issues adding your private key to CircleCI, you can contact or check CircelCI support.

Upon adding the key, you'll see the fingerprint of your newly added key. As fingerprints are safer than exposing private keys directly, CircleCI uses fingerprints to identify private keys in its scripts.

After that, you need to ensure that the “pass secrets to builds from forked pull requests” options on our Advanced Setting Page are set to Off. You can locate the Advanced Setting link on the side menu of our project setting page.

To complete our security checks, please ensure that you delete the private key file from the project root folder.

Next, we need to submit our public key to our GitHub account. You can do this by going to the Settings tab of your GitHub project repository. On the side menu, click Deploy Keys. Then click Add deploy key on the Deploy Keys page, and the form below will appear:

Input a relatable name in the title field, e.g., “CircleCI Deployment Key”. In the Key field, paste the content in your public key file “deploy_key.pub” and check the Allow write access checkbox. Then click Add key.

Your key will be displayed in the list of deployed keys. To finish up, we need to add the fingerprint of our private key from CircleCI to our configuration file. Our deploy steps will look like this below:

- run:
          name: Install and configure dependencies
          command: |
            npm install gh-pages --save-dev
            git config user.email "youremail@gmail.com"
            git config user.name "daacode"
      - add_ssh_keys:
          fingerprints:
            - "c2:08:17:00:f0:90:43:32:bc:5c:1f:28:6d:01:25:c2"
      - run:
          name: Deploy docs to gh-pages branch
          command: './node_modules/.bin/gh-pages --dotfiles --message "[skip ci] Updates" -d dist'
      - store_artifacts:
          path: test-results.xml
          prefix: tests
      - store_test_results:
          path: test-results.xml

Make sure you replace the fingerprint used here with your own.

Here is the complete configuration file config.yml:

version: 2.1
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: cimg/node:12.16.0
    steps:
      - checkout
      - run:
          name: update-npm
          command: "sudo npm install -g npm@6"
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: install-packages
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
          paths:
            - ./node_modules
 
      - run:
          name: test
          command: npm run test
 
      - run:
          name: build-project
          command: npm run generate:gh-pages
      
      - run:
          name: Install and configure dependencies
          command: |
            npm install gh-pages --save-dev
            git config user.email "yourgmail@gmail.com"
            git config user.name "daacode"
      - add_ssh_keys:
          fingerprints:
            - "c2:08:17:00:f0:90:43:32:bc:5c:1f:28:6d:01:25:c2"
      - run:
          name: Deploy docs to gh-pages branch
          command: './node_modules/.bin/gh-pages --dotfiles --message "[skip ci] Updates" -d dist'
      - store_artifacts:
          path: test-results.xml
          prefix: tests
      - store_test_results:
          path: test-results.xml

Finally, commit your changes and push to the main branch once more to trigger the deployment. As soon as you push, it will initiate a new build process, which will be successful this time. Then click the deployment tab and check the test section. You will discover that all our tests are running successfully:

If you want to verify that our application is deployed, visit your GitHub page URL "https://[your_github_username.github.io/nuxt-cicd]", and view the deployed nuxt application. You will see the homepage of the nuxt application.

You can find the complete repo for this tutorial here on GitHub.

Conclusion

Utilizing the CICD pipeline can help reduce manual errors and provide feedback to developers, allowing for faster product iteration. Developers building server-side rendered applications with Nuxt.js should leverage these modern processes to deploy their applications. We demonstrated how to leverage CICD to successfully deploy a Nuxt.js application to GitHub Pages. CircleCI offers a comprehensive list of configuration options, so we could tailor our configuration to suit our specific needs and deploy it to other hosting providers.