This tutorial covers:

  1. Set up a continuous deployment server
  2. Add and execute any custom step to your build process
  3. Deploy your application to Netlify

React, a front-end framework for building user interfaces, uses component-based architecture and non-opinionated design principles, making it a developer favorite. React has been widely adopted and has a large community of developers behind it. Netlify is a popular framework for hosting React applications, but it does not provide your team with the highest level of control over the deployment process. As a result, you are not able to perform important tasks like running automated tests.

In this tutorial, you will learn how to take control over the deployment process by using CircleCI as your continuous deployment server. With the system you set up using this tutorial, you can perform any custom step you need to complete your build process and deploy your React application to Netlify.


To follow along with this tutorial, you will need:

  1. Node.js installed on your system (version 12 or newer)
  2. A Netlify account
  3. A CircleCI account
  4. A GitHub account

Our tutorials are platform-agnostic, but use CircleCI as an example. If you don’t have a CircleCI account, sign up for a free one here.

With all these installed and set up, we can begin the tutorial.

Creating a new React site

Choose a location within your system to create the React site that will be deployed to Netlify. Run this command:

npx create-react-app netlify-react-app

This command will invoke the create-react-app npm package to scaffold a new React application.

The result is a React project created in the netlify-react-app folder. Use these commands to run the project:

cd netlify-react-app
npm start

The commands boot up the React site at the local URL: http://localhost:8000. Load this address in your browser.

React site - local

Setting up the GitHub project

You need to set up your React project on GitHub before you can get it on Netlify and CircleCI. First, install the Netlify CLI package as a development dependency in your React project. Run this command at the root of your project:

npm install --save-dev netlify-cli

Note: Adding the Netlify CLI as a dependency prevents breaking changes for deployments in CI environments.

You can now push your project to GitHub. Once your project is on GitHub, create a new branch. Give this branch any name you want; for this tutorial I will name it netlify-deploy-ignore.

Create deploy branch - GitHub

You may be wondering why you need this branch. Netlify needs a project branch to automatically trigger an application’s deployment. When changes are pushed to this branch, Netlify will initiate the deployment process. You want to avoid a situation where both Netlify and your CircleCI pipeline are running two deployment processes in parallel. This new branch acts as a decoy for Netlify to monitor. Do not push changes to this branch. Its purpose is to “distract” the Netlify deployment process so that you can use CircleCI for deployment. You can make this a protected branch on GitHub so that no one on your team pushes to it by mistake.

Creating the Netlify application

To create a new Netlify application, go to your Netlify dashboard and click the New Site from Git button. Next, select GitHub as your provider and search for the project.

Select your project - Netlify

Select the project and go to the next step to select a branch for Netlify to deploy from. Select your decoy branch.

Select a branch - Netlify

Next, click the Deploy site button so that Netlify performs the very first deployment of your site. Click the link, which should look like:

Application live - Netlify

There are two configuration values you will need to get from your Netlify app and account to perform automated deployments in your CircleCI pipeline.

  • The APP ID for the application you just created can be found in the Site Details section of your Netlify app.
  • The Personal Access token allows access to your Netlify account from your deployment pipeline. Generate an access token at User Settings > Applications.

Save your access token in a secure place because Netlify will not allow you another view of this value after you create. You will only be able to change it.

Setting up the project on CircleCI

Time to set up your project on CircleCI. Add the .circleci folder to the root of your project. In it, add an empty config.yml file. You will be adding the configuration to this file in the next section. Push your changes to the GitHub project.

Note: GitLab users can also follow this tutorial by pushing the sample project to GitLab and setting up a CI/CD pipeline for their GitLab repo.

Next, go to the Add Projects page on the CircleCI dashboard to add the project.

Add project - CircleCI

Click Set Up Project. This will load a dialog where CircleCI automatically detects your configuration file.

Add config - CircleCI

Click Let’s Go to trigger your build pipeline for the first time. The build will fail because you have not added code to the configuration yet. You will perform this step later on.

Before you write the configuration you will need to add the Netlify APP ID and access token as environment variables on your CircleCI project.

Make sure your project is the currently selected project on the Pipelines page. Click the Project Settings button. On the settings page, select Environment Variables from the side menu. On this new page, click the Add Environment Variable button and enter this information:

  • NETLIFY_SITE_ID: The API ID from your Netlify application
  • NETLIFY_ACCESS_TOKEN: Your Netlify personal access token.

Environment variables - CircleCI

Writing the deployment configuration

The last step in the process is to write the deployment configuration. Open the config.yml file and add this configuration:

version: 2.1
    working_directory: ~/repo
      - image: cimg/node:16.13.2
      - checkout
      - run:
          name: Update NPM
          command: "sudo npm install -g npm"
      - restore_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
      - run:
          name: Install Dependencies
          command: npm install
      - save_cache:
          key: dependency-cache-{{ checksum "package-lock.json" }}
            - ./node_modules
      - run:
          name: Build React App
          command: npm run build
      - save_cache:
          key: app-build-cache-{{ .Branch }}
            - ./build
      - run:
          name: Deploy to Netlify
          command: ./node_modules/.bin/netlify deploy --site $NETLIFY_SITE_ID --auth $NETLIFY_ACCESS_TOKEN --prod --dir=build
  version: 2
      - build:
                - main

In this configuration, the project is checked out of the repository and the project dependencies are installed and cached. After caching the dependencies, the React build command npm run build runs. It creates a production build of the application in the build directory at the root of the project, which is then cached.

Finally, the Netlify CLI deploys the site using the $NETLIFY_SITE_ID and $NETLIFY_ACCESS_TOKEN variables. The workflow configuration then ensures that only the main branch triggers a deployment to Netlify.

Before you push this configuration for CircleCI to deploy the site, go Change the React message in the <p> tag to this:

<p>Successfully Deployed <code>A React application</code> to Netlify with CircleCI</p>

This enables you to view a change in the deployed application.

Finally, commit all your changes and push to GitHub. This will automatically trigger the deployment pipeline and a successful build.

Successful build - CircleCI

Click the build to review the deployment details.

Build details - CircleCI

With this successful build, visit your website again to verify the changes you deployed. It should display the new message.

Changes deployed - live application


To confirm that Netlify is not running a parallel deployment, check your Netlify deployment logs. There is only one deployment in the Production deploys, the first one that was triggered by the branch netlify-deploy-ignore. The rest don’t show a branch because they were triggered by the CircleCI pipeline.

Deployment logs - Netlify


There you have it, custom deployment of a React site to Netlify using CircleCI. This setup gives you more flexibility and control of your React deployments to Netlify. That gives your team the ability to run more custom steps within the process.

Happy Coding!

Fikayo Adepoju is a LinkedIn Learning ( Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.

Read more posts by Fikayo Adepoju