Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Configure a Node.js application on CircleCI

7 months ago3 min read
Cloud
Server v4.x
Server v3.x
On This Page

Node.JS Logo

Setup your Node.JS App

Learn to build, test, and deploy your Node.JS app.

Completion Time 15 min task

OR

Overview

This is a quickstart guide for integrating a Node.JS project with CircleCI. This guide is designed to help you create a basic CircleCI configuration file to build, test and deploy your Node.JS project. After completing this quickstart you can edit and optimize the config to fit the requirements of your project.

Prerequisites

If you do not have a Node.JS project, but would like to follow this guide, you can use our sample project, which is hosted on GitHub and is building on CircleCI. Consider forking the repository and rewriting the configuration file as you follow this guide.

Configuration walkthrough

Every CircleCI project requires a configuration file called .circleci/config.yml. Follow the steps below to create a complete config.yml file.

1. Specify a version

Every CircleCI config.yml starts with the version key. This key is used to issue warnings about breaking changes.

version: 2.1

2.1 is the latest CircleCI version, and it ensures you have access to all our latest features and improvements.

2. Use the Node orb

The Node.js orb contains a set of prepackaged CircleCI configurations you can use to easily install Node.js and its package managers (npm, yarn). Best of all, packages are installed with caching by default, and support for Linux x86_64, macOS x86_64, and Arm64 is automatically included. Learn more about orbs.

To add the orb to your config, insert:

orbs:
  node: circleci/node@5.0.2

Note: When using an orb, it is a good idea to check the Orb Registry to ensure you are using the most recent version, or the version that fits best with your specific project.

3. Create jobs

Jobs are the building blocks of your config. Jobs are collections of steps, which run commands/scripts as required. All of the steps in the job are executed in a single unit, either within a fresh container or Virtual Machine. Learn more about jobs on the Jobs and Steps page.

A common ask from developers who are getting started with CircleCI is to perform 3 basic tasks: build, test and deploy. This section guides you through each of the config changes needed. Because we are using the official Node orb, we can use commands that are built into the orb to keep our config simple and succinct:

a. Build and test the app

If you are using yarn:

jobs:
  build_and_test: # this can be any name you choose
    executor: node/default # use the default executor defined within the orb
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: yarn
      - run:
          command: yarn test
          name: Run tests
      - run:
          command: yarn build
          name: Build app
      - persist_to_workspace:
          root: ~/project
          paths: .

Similarly, if you are using npm:

jobs:
  build_and_test: # this can be any name you choose
    executor: node/default # use the default executor defined within the orb
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: npm
      - run:
          command: npm run test
          name: Run tests
      - run:
          command: npm run build
          name: Build app
      - persist_to_workspace:
          root: ~/project
          paths:
            - .

Because we are using the Node orb, this job will install your Node packages with automated caching and best practices applied. Note that it requires a lock file.

b. Deploy the app

In this quickstart guide, we will deploy to Heroku. We can do this using the official Heroku orb by adding a new line into our orb section. The Heroku orb contains a set of prepackaged CircleCI configurations you can use to deploy applications to Heroku. Learn more about the Heroku orb.

orbs:
  node: circleci/node@4.7.0
  heroku: circleci/heroku@1.2.6

We then need to add a job to our list to take care of the deploy step:

jobs:
  # ...previous job(s)...
  deploy: # this can be any name you choose
    executor: heroku/default
    steps:
      - attach_workspace:
          at: ~/project
      - heroku/deploy-via-git:
          force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git

3. Create a workflow

A workflow is a set of rules for defining a collection of jobs and their run order. Workflows support complex job orchestration using a set of configuration keys to help you resolve failures sooner. Inside the workflow, you define the jobs you want to run. CircleCI will run this workflow on every commit. Learn more about workflow configuration.

workflows:
  build_test_deploy: # this can be any name you choose

4. Add jobs to the workflow

Now that we have our workflow, build_test_deploy, we can use it to orchestrate the running of our build_and_test and deploy jobs. Refer to the Using Workflows to Orchestrate Jobs page for more details about orchestrating jobs with concurrent, sequential, and manual approval workflows.

workflows:
  build_test_deploy: # this can be any name you choose
    jobs:
      - build_and_test
      - deploy:
          requires:
            - build_and_test # only deploy if the build_and_test job has completed
          filters:
            branches:
              only: main # only deploy when on main

5. Conclusion

You just set up a Node.js app to build on CircleCI. Check out your project’s pipeline page to see how this looks when building on CircleCI.

Full configuration file

version: 2.1
orbs:
  node: circleci/node@5.0.2
  heroku: circleci/heroku@1.2.6

jobs:
  build_and_test:
    executor: node/default
    steps:
      - checkout
      - node/install-packages:
          pkg-manager: yarn
      - run:
          command: yarn test
          name: Run tests
      - run:
          command: yarn build
          name: Build app
      - persist_to_workspace:
          root: ~/project
          paths:
            - .

  deploy: # this can be any name you choose
    executor: heroku/default
    steps:
      - attach_workspace:
          at: ~/project
      - heroku/deploy-via-git:
          force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git

workflows:
  test_my_app:
    jobs:
      - build_and_test
      - deploy:
          requires:
            - build_and_test # only deploy if the build_and_test job has completed
          filters:
            branches:
              only: main # only deploy when on main

See also


Suggest an edit to this page

Make a contribution
Learn how to contribute