--- title: "Configure a Node.js application on CircleCI" description: "Build and test a Node.js application on CircleCI. Follow a configuration walkthrough to create a basic config.yml file for your JavaScript project." platform: "Cloud, Server" doc_version: "Server" last_updated: "2026-10-07" --- > For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md). > > For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt). # Configure a Node.js application on CircleCI This quickstart guide covers 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 * An account on your CircleCI Server instance. * A Node.js project located in a GitHub repository. ## Configuration walkthrough Every CircleCI project requires a configuration file called [`.circleci/config.yml`](https://circleci.com/docs/reference/configuration-reference/). 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. ```yaml 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](https://circleci.com/developer/orbs/orb/circleci/node) contains a set of prepackaged CircleCI configurations you can use to 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 is automatically included. Learn more about [Orbs](https://circleci.com/docs/orbs/use/orb-intro/). To add the orb to your config, insert: ```yaml orbs: node: circleci/node@5.0.2 ``` When using an orb, check the [Orb Registry](https://circleci.com/developer/orbs) to confirm you are using the most recent version. Alternatively, use the version that best fits 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](https://circleci.com/docs/guides/server/orchestrate/jobs-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: ```yaml 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: ```yaml 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](https://www.heroku.com/). 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](https://circleci.com/developer/orbs/orb/circleci/heroku). ```yaml 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: ```yaml 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 ``` Environment variables containing the necessary secrets such as `HEROKU_API_KEY` and `HEROKU_APP_NAME` can be set up in the CircleCI web app. Learn more about [Environment Variables](https://circleci.com/docs/guides/server/security/set-environment-variable/#set-an-environment-variable-in-a-project). ### 4\. 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](https://circleci.com/docs/reference/configuration-reference/#workflows). ```yaml workflows: build_test_deploy: # this can be any name you choose ``` ### 5\. 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](https://circleci.com/docs/guides/server/orchestrate/workflows/) page for more details about orchestrating jobs with concurrent, sequential, and manual approval workflows. ```yaml 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: pipeline.git.branch == "main" # only run the deploy job on the main branch ``` ### 6\. Conclusion You just set up a Node.js app to build on CircleCI. Check out your project’s [Pipeline Page](https://circleci.com/docs/guides/server/orchestrate/pipelines/) to see how this looks when building on CircleCI. **Deploy options?** For alternative deployment targets, search the [orb registry](https://circleci.com/developer/orbs), where you will find integrations such as [Kubernetes](https://circleci.com/developer/orbs/orb/circleci/kubernetes), [AWS ECS](https://circleci.com/developer/orbs/orb/circleci/aws-ecs), [GCP GKE](https://circleci.com/developer/orbs/orb/circleci/gcp-gke), and more. ## Full configuration file ```yaml 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: pipeline.git.branch == "main" # only run the deploy job on the main branch ``` ## See also * [Continuous deployment of Node apps to Heroku](https://circleci.com/blog/continuous-deployment-to-heroku/) * [Continuous deployment of Node.js to Azure VM](https://circleci.com/blog/cd-azure-vm/) * [Troubleshoot Node.js build and test suite timeouts](https://support.circleci.com/hc/en-us/articles/360038192673-NodeJS-Builds-or-Test-Suites-Fail-With-ENOMEM-or-a-Timeout) * [Parallelism and Test Splitting](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/)