Heroku and CircleCI : Automated CI/CD Process for a NuxtJS

Published with permission from . Alvin Lee Manually deploying a project is pretty easy when teams are small. However, as projects and teams grow they usually in their DevOps to automate their testing and deployment. This is when deployments—and the setup of deployments—can get complicated. NuxtJS turn to CI/CD In this article, we’ll look at how to easily set up an automated CI/CD system for a NuxtJS project using and . We’ll walk through all the details from setting up your GitHub repository to automating your tests to pushing your code changes. Then we’ll look at some suggested next steps. Heroku CircleCI What is NuxtJS? First, here is a little background on NuxtJS, and why developers might choose it as part of their stack. When was first released, developers fell in love. With its simple template syntax and component structure, Vue.js makes it easy to spin up beautiful single-page applications (SPAs) with ease. However, developers soon realized that SEO was a problem. Since SPAs are deployed as a "shell" and the content isn't inserted until runtime, they learned . Because of this, developers needed a solution for handling server-side rendering (SSR) of their Vue.js applications. Vue.js it could be difficult for search engines to accurately index the contents Enter . NuxtJS NuxtJS is an open-source framework that combines all of the oft-used Vue.js libraries, bundling in , , and to provide Vue.js developers with the architecture for a smoother development experience. With NuxtJS, developers can get an SEO-friendly Vue.js application (with SSR) up and running within minutes. Vue Router Vuex Vue Server Renderer Our Sample Project Now let's look at our sample project and deployment setup. For this project, we’ll be using GitHub as our repository, Heroku as our host, and CircleCI as our CI/CD tool. Heroku is a PaaS solution that makes it easy to deploy and manage apps. CircleCI provides cloud-based CI/CD, running automated jobs in containers as soon as project code is pushed to GitHub. These jobs perform tests, send success or failure notifications, and then deploy built applications to cloud service environments. In the end, we want our outcome to be: When we push our master branch to GitHub, an automated process will run all of our tests and then (if all the tests pass) deploy the application to Heroku. To that end, I'll take you through the following steps: Set up a GitHub repository.Create a basic NuxtJS application.Write a few tests for our application.Manually deploy the NuxtJS application to Heroku.Configure CircleCI to run our test suite upon push to GitHub.Configure CircleCI to deploy our application to Heroku upon passing tests. Sound pretty simple? It will be. Let’s go! 1. Set up a GitHub repository This tutorial requires an account with GitHub. A basic GitHub Free account will be sufficient. We will set up a GitHub repository to house our project code. Later, we’ll connect our GitHub account with our CircleCI account. Whenever we push code to GitHub, this action will trigger a webhook to notify CircleCI to begin the CI/CD automation process. On the “Your Repositories” page in GitHub, click on the “New” repository button. Choose any name you’d like for this private repository. For this tutorial, we will call our repository . my-heroku-nuxt-app Click on “Create repository” to finish up. Then, clone the repository on your local machine. In the command below, make sure to use your own GitHub username. Notice that we are cloning the empty repository into a folder called . app ~ -heroku-nuxt-app.git app Cloning into ... warning: You appear to have cloned an empty repository. /$ git clone git@github.com:[GITHUB USERNAME]/my 'my-heroku-nuxt-app' Excellent. Now that we have our app folder, let’s fill it up with a shiny, new NuxtJS application. 2. Create a NuxtJS Application Just for your reference, we will be using Node.js v10.20.0 throughout this tutorial. We’ll also be using as our package manager. yarn From within your app folder, run the following command to create a new NuxtJS application: ~/app$ yarn nuxt-app -nuxt-app v3 ✨ Generating Nuxt.js . ? my-heroku-nuxt-app ? programming JavaScript ? the manager Yarn ? UI framework ? Nuxt.js modules ? linting tools ? framework Jest ? rendering Universal (SSR / ) ? development tools create create .0 .0 project in Project name Choose language Choose package Choose None Choose None Choose None Choose test Choose mode Static Choose None The interactive prompts will ask you to choose some options. You can chose whatever you’d like for “Project name,” but it’s important that you choose the options which I have shown in bold above. By the way, if you would like to use instead of , you can use the command instead of the command above. npm yarn npx create-nuxt-app yarn create Verify that your application works by running from the command line. Your browser window should look like the following: yarn dev Great! Now that our application is up and running, let’s write some tests. 3. Create the Tests for Our NuxtJS Application We’ll write tests just for our page. Keep in mind that we are not planning to build anything beyond this basic boilerplate NuxtJS application. Our goal is to learn how to automate testing and deployment to Heroku. index For testing, we'll use , which is a popular JavaScript testing framework. It's easy to use and lightning fast. When we created our NuxtJS application above, we opted to bundle in Jest. Jest In the folder, create a new test file called . We will write three tests which verify that our page has certain content. app/pages index.test.js index // FILE: ~/app/pages/ .test.js { mount } describe( , () => { const = mount( ) describe( , () => { const element = .find( ) it( , () => { expect(element.text()).toEqual( ) }) }) describe( , () => { const links = .find( ) describe( , () => { it( , () => { const link = links.find( ) expect(link.text()).toEqual( ) }) }) describe( , () => { it( , () => { const link = links.find( ) expect(link.text()).toEqual( ) }) }) }) }) index import from '@vue/test-utils' import index from './index.vue' 'index page' wrapper index 'app title' wrapper '.title' 'displays app title' 'my-heroku-nuxt-app' 'links' wrapper '.links' 'nuxtjs' 'contains link with correct text' '[href="https://nuxtjs.org/"]' 'Documentation' 'github' 'contains link with correct text' '[href="https://github.com/nuxt/nuxt.js"]' 'GitHub' Let’s run our tests. We won’t be concerned about test coverage, so let’s include the - . -coverage false flag ~ ndex.test.js index page app title ✓ displays app title ( ms) links nuxtjs ✓ contains link correct text ( ms) github ✓ contains link correct text ( ms)Test Suites: passed, total Tests: passed, total Snapshots: total Time: s, estimated s Ran all test suites. Done s. /app$ yarn test --coverage false PASS pages/i 3 with 1 with 1 1 1 3 3 0 1.405 2 in 2.21 Now, with tests working, let’s check in our code: ~/app$ git ~/app$ git commit -m ~/app$ git push origin add . "Create nuxt app with tests." Nicely done. Now, we have a NuxtJS application with a few tests (which are passing), and we’ve pushed our branch to GitHub. master 4. Manually Deploy Our Application to Heroku Before we build in automation, let’s walk through a basic, manual deployment to Heroku. This will help us understand what we’re doing later on when we automate deployment through CircleCI. If you don't already have one, . will work fine for this example. Then, log into your account. From the dashboard, click on “New” and then “Create new app”. set up a new account with Heroku The free plan Choose a name for your application. For this tutorial, we’ll go with the same name that we’ve been using thus far. Note that app names on Heroku must be unique across their system. So, it’s possible that is not available. If that’s the case, choose another name and take note of that for substitution as we go through this tutorial. my-heroku-nuxt-app After the app has been created, you will see app deployment settings. We will be using the “Heroku Git (Use Heroku CLI)” method for deployment. We’ll use this as we deploy manually from our local machine command line, and then we’ll configure CircleCI to deploy via the command line, too. Further down on Heroku’s deployment settings page, you will see a link with instructions for on your local machine. After installing the Heroku CLI, log into Heroku from the command line: installing the Heroku CLI ~ auth/cli/browser/ ... Logging ... done Logged ... /app$ heroku login heroku: Press any key to open up the browser to login or q to exit: Opening browser to https:/ /cli-auth.heroku.com/ in in Since our GitHub repository for this project already exists, we want to add the new Heroku remote. Make sure to use the Heroku application name that you chose above, if wasn’t available. my-heroku-nuxt-app ~/ $ heroku git:remote -a my-heroku-nuxt- app app Next, we want to set a few Heroku configuration variables to get our production deployment running. These instructions come from the . NuxtJS documentation on deploying to Heroku ~/app$ heroku config: =0.0.0.0 ~/app$ heroku config: =production set HOST set NODE_ENV Now, we can push our NuxtJS application to Heroku for deployment. ~/app$ git push heroku Enumerating objects: , done. Counting objects: % ( / ), done. Delta compression using up to threads Compressing objects: % ( / ), done. Writing objects: % ( / ), KiB | MiB/s, done. Total (delta ), reused (delta ), pack-reused remote: Compressing source files... done. remote: Building source: Node.js app detected Creating runtime environment Installing binaries Installing dependencies Build Pruning devDependencies Caching build Build succeeded! Discovering process types Compressing... Launching... remote: https: remote: Verifying deploy... done. 17 100 17 17 4 100 14 14 100 17 17 167.78 5.99 17 0 0 0 0 : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote : -----> remote //my-heroku-nuxt-app.herokuapp.com/ deployed to Heroku The command above is where all of the magic happens. Heroku detects that this is a Node.js app, and then it creates the proper deployment environment and installs all dependencies. After installing dependencies, Heroku also runs the script command found in your — this bundles all of the files needed for the client and for the server. build package.json When we visit the URL for our Heroku app, we see our NuxtJS application up and running on the web: Just like that… our NuxtJS SSR application has been deployed to Heroku and is live. All that’s left to do is build in automated CI/CD through CircleCI. 5. Set Up Automated Testing with CircleCI Create a new account at by clicking on “Log In with GitHub”. CircleCI By logging in with GitHub, you authorize CircleCI to access all of your repositories. Within CircleCI’s dashboard, you’ll be able to select which of your GitHub repositories you want CircleCI to monitor. From the CircleCI projects dashboard, you will see your GitHub repository named — click on the “Set Up Project” button to its right. my-heroku-nuxt-app CircleCI will choose a config template for you to start with (by default, it chooses the “Hello World” template). Shortly, we'll provide our own CircleCI config file. For now, select “Hello World” and click on “Start Building”: This will pop up a modal saying that CircleCI will create a new branch and add this config template to that branch. But, we don’t need CircleCI to do this for us, so select “Add Manually”. We’re told that we will need to create a sub-folder in our repository root folder, and then add a to that sub-folder. That’s what we’re about to do. We don’t need to download the template file, since we’re going to write our own. So, just click on “Start Building”. .circleci config.yml config.yml When you set up your project for monitoring by CircleCI (and because CircleCI has been authorized to access your GitHub repositories), CircleCI will add a new public key to your GitHub repository’s settings. CircleCI will immediately execute a workflow for this project. You’ll notice that this first build attempt fails. That’s because CircleCI is looking for the file in the sub-folder of the branch of your project repository. That file doesn't exist yet, so let's create it now. config.yml .circleci master In your project root folder, create a new sub-folder called : .circleci ~ $ mkdir /app .circleci In that folder, create a new file named . We’re going to break this part of the tutorial into two separate parts. First, we’ll configure CircleCI to run our tests. Then, after we get that up and running, we’ll move on to configuring for Heroku deployment. config.yml The contents of should be the following: config.yml : : : : - : circleci/ : . : ~/project : - checkout - : : Fetch dependencies : yarn install --no-progress --non-interactive --silent --pure-lockfile - : : Run test suite : yarn test_ci - : : ~/project : - . : : : - run-test-suite // FILE: ~/app/.circleci/config.yml version 2.1 jobs run-test-suite docker image node 10.20 0 working_directory steps run name command run name command persist_to_workspace root paths workflows test-and-deploy jobs Let’s walk through what the above configuration does: We define a new job called . run-test-suite This job sets up an environment that supports Node.js with the version that we want. Then, this job executes four steps. It checks out the repository code, installs dependencies, runs the test suite by running , and then saves the current workspace folder to the machine, so that other jobs can still access the contents in its current state. yarn test_ci Our overall workflow, called , only has one job in it: . test-and-deploy run-test-suite You may have noticed that CircleCI will call from within our project folder to run the test suite. But we haven’t defined in our script commands yet. We'll define that command with an . This affects how Jest handles . Though we don't have any of those in our project right now, you'll want to keep this in mind in case you write snapshot tests for your projects in the future.. Since we’re updating our file, let’s also turn off code coverage testing when running Jest: yarn test_ci test_ci package.json extra flag that tells Jest to run in continuous integration mode snapshot tests package.json Excerpt from FILE: ~ : { : , : , : , : , : , : }, // /app/package.json ... "scripts" "dev" "nuxt" "build" "nuxt build" "start" "nuxt start" "generate" "nuxt generate" "test" "jest --coverage false" "test_ci" "yarn test --ci" ... Now, let’s add our new file and our updated file to git staging, and then commit them. .circleci/config.yml package.json ~/app$ git ~/app$ git commit -m add . "Add CircleCI config for testing, update package.json" We push our new commit to : master ~/app$ git push origin Within a few seconds, you should see a new pipeline entry on your CircleCI dashboard for this project. The workflow for your project, on the branch, will begin executing. It will execute the first and only job, which is to . Our tests should pass, and everything should be green. test-and-deploy master run-test-suite 6. Set Up Automated Deployment to Heroku For our final step, we want to configure CircleCI to deploy the code to Heroku when our tests pass. To do this, we need to modify our file with the CircleCI configuration. We will make use of CircleCI’s . CircleCI Orbs are reusable packages used to simplify configuration. CircleCI has a which simplify integration with third-party technologies (like Heroku). Our updated should look like the following (changes in ): config.yml Heroku orb huge registry of pre-built orbs config.yml bold : : : circleci/heroku . : : : - : circleci/ : . : ~/project : - checkout - : : Fetch dependencies : yarn install --no-progress --non-interactive --silent --pure-lockfile - : : Run test suite : yarn test_ci - : : ~/project : - . : : - : circleci/ : . : ~/project : - : : ~/project - heroku/deploy-via-git : : : - run-test-suite - : : - run-test-suite : : : master // FILE: ~/app/.circleci/config.yml version 2.1 orbs heroku @1 0.0 jobs run-test-suite docker image node 10.20 0 working_directory steps run name command run name command persist_to_workspace root paths deploy-to-heroku docker image node 10.20 0 working_directory steps attach_workspace at workflows test-and-deploy jobs deploy-to-heroku requires filters branches only Here is what we’ve added: In addition to the original job, we now have a job. It also uses the same Node.js version and working directory. run-test-suite deploy-to-heroku The job has two steps: First, it attaches to the workspace which we persisted in the previous job. Second, it calls the command, which is defined in CircleCI’s Heroku orb. Essentially, it runs a Heroku CLI command similar to what we did when we manually deployed our application to Heroku above. deploy-to-heroku deploy-via-git We have added this new job to our test-and-deploy workflow, but we put some constraints on this job. First, it will only run after a successful run of the job. Also, it will only run if CircleCI is responding to a webhook for the branch from our GitHub repository. This means that all branches pushed to GitHub will result in a run of the job. But, only the branch will continue on with the deploy-to-heroku job. This make sense because we would, of course, only want to deploy the branch to production. deploy-to-heroku run-test-suite master run-test-suite master master Before this new CircleCI configuration will work, however, we need to update our CircleCI project settings with some environment variables related to our Heroku app deployment. In your CircleCI project settings, click on “Environment Variables”. We need to add two environment variables. The first is , which can be found at your Heroku account settings. HEROKU_API_KEY Click on “Reveal” and then copy/paste that value over in CircleCI as the value for the environment variable. HEROKU_API_KEY The second environment variable we need in CircleCI is , which is the name of the Heroku app that you established when creating the app. (For our tutorial, it’s .) HEROKU_APP_NAME my-heroku-nuxt-app After adding these two environment variables, your CircleCI project settings should look similar to below: Now that we’re all set, we can stage and commit our updated file to git, then push to GitHub: .circleci/config.yml ~/app$ git ~/app$ git commit -m ~/app$ git push origin add . "Update CircleCI config for Heroku deployment" When we do this push to GitHub, here is what happens: The new commit on the branch is pushed to GitHub. master GitHub, receiving a new push, sends a webhook to CircleCI, indicating the name of the branch that just got a new commit. CircleCI goes into action to launch the workflow for this project. test-and-deploy The first job in the workflow is . All of the tests run and they all pass. run-test-suite The job runs next, since succeeded the branch that just got a new commit is . deploy-to-heroku run-test-suite and master Armed with the environment variable (which gives CircleCI authorization to access your Heroku apps) and the environment variable (which lets CircleCI know which Heroku app to deploy), the job pushes the code to Heroku. HEROKU_API_KEY HEROKU_APP_NAME Upon receiving the code pushed from CircleCI, Heroku builds the NuxtJS application and then starts up the server. Review and Wrap-Up And there you have it. You have just set up complete CI/CD automation of your NuxtJS SSR application. By simply pushing your project to GitHub, your project tests will run, and your project will deploy to Heroku. Let’s quickly review what we did: We set up a GitHub repository for our project. We created a new NuxtJS application, using .We wrote tests for our NuxtJS application, using Jest. yarn create nuxt-app We manually deployed our project to Heroku, using the Heroku CLI. We set up CircleCI to automate running our test suite whenever we push code to GitHub. We set up CircleCI to automate deployment to Heroku whenever we push the branch to GitHub and all of the tests pass. master Next Steps You now have the foundation you need to take this to the next level. From here, what might be some next steps you could take to build on this new knowledge? Expanding on this bare bones NuxtJS application, you can build out new features accompanied by comprehensive tests. Now that you’ve automated test runs and deployment to Heroku, all you need to worry about is writing tests, writing code, and pushing to GitHub. Or, if you already have an existing NuxtJS application, you can apply the Heroku deployment and CircleCI automation steps to your existing project. In less than an hour of your time, you can build in CI/CD. Because deployment of NuxtJS SSR applications to Heroku is so quick and simple, you reduce the friction you’ll encounter when it’s time to go live. And, with CI/CD baked into your development process, you free up yourself and your team from another checklist of things to do when it is time to ship your code.