Create React App is one the most popular tools for creating React app.
With just three dependencies, you get support for React, JSX, ES6, polyfills, a development server, auto prefixed CSS, tests, service workers, and many more things.
This post presents a quick guide to set up a React app with this tool and configure some of its more important features.
The only prerequisite for using this tool is having Node.js version 6 or superior installed.
Creating a React app
Use one of the following commands to create a new app:
#Using npx npx create-react-app app-name #Using npm init <initializer> npm init react-app app-name #Using yarn 0.25+ yarn create react-app app-name
These commands create a directory with the given app name of the app, an initial project structure (see the template here) and install hundreds of packages as the dependencies.
Now, if you look at the generated package.json
file, you’ll only see three dependencies: react, react-dom, and react-scripts.
react-scripts is the library that handles all the configuration and brings most of the dependencies of the project, like babel, eslint, and webpack (if you’re curious, see the complete list in its package.json file).
Understanding react-scripts is the key to understanding the inner workings of Create React App.

Upgrading the versions of the dependencies
One of the advantages of having so few dependencies is that they are easy to upgrade (or downgrade).
You only have to execute npm install
with the flags — — save — -save-exact
to specify the exact version. The package.json
will be updated and the new versions of the dependencies downloaded.
For example, to change to the version 1.1.4 of react-scripts, execute:
npm install --save --save-exact react-scripts@1.1.4 # or yarn add --exact react-scripts@1.1.4
Also, don’t forget to consult the changelog of react-scripts and react to look for breaking changes.
Configuring linting
ESLint is configured by default (you can see the configuration here), and its output is shown in the terminal as well as the browser console.
Officially, at the time of this writing, you cannot override this configuration. If you want to enforce a coding style, you can install and use Prettier (it’s not integrated right now).
The only thing you can do is to configure your code editor to report linting warnings by installing a ESLint plugin for your editor and adding a .eslintrc
file to the project root:
{ "extends": "react-app" }
Optionally, you can add your custom rules to this file, but they will only work in your editor.
Unofficially, you can use something like react-app-rewired to override the default configuration.
Starting the application
To run the application, execute npm start
, which is a shortcut to:
react-scripts start
This script executes a Webpack development server:
- With hot reloading enabled (if you make a change to the application, this is reloaded in the browser to reflect that change)
- Using the port 3000 by default (or another one if the chosen port is occupied)
In mac, the app is opened in Chrome if it’s installed. Otherwise, like in other OSs, the default browser is used.
In addition, errors are shown in the console terminal as well as the browser.
You can see the whole start script here.
Adding images and styles
You have two options when adding images, styles or other files (like fonts):
- The
src
folder, using the module system - The
public
folder, as static assets
Everything you place inside the src
folder will be handled by Webpack, which mean the files will be minified and included in the bundle generated at build time.
This also means that the assets can be imported in JavaScript:
import './styles.css';
import logo from './logo.png';
// ...
const image = <img src={logo} className="image" alt="Logo" />;
Importing images that are less than 10,000 bytes returns a data URI instead of a path to the actual image as long as they have the following extensions:
- BMP
- GIF
- JPG or JPEG
- PNG
Another advantage of using this folder is that if you don’t reference the file correctly (or if you accidentally delete it) a compilation error is generated.
On the other hand, you can also add files to the public
folder, however, you’ll miss the advantages described above because they will not be processed by Webpack, they will only be copied into the build
folder.
Another thing is that you cannot reference files inside the src
folder in the public
folder.
However, to reference the files in the public
folder, you can use the variable PUBLIC_URL
like this:
<img src="%PUBLIC_URL%/logo" alt="logo" />
Or with the variable process.env.PUBLIC_URL
in JavaScript:
const image = <img src={process.env.PUBLIC_URL + '/logo.png'} alt="Logo" />;
Setting environment variables
In addition to the variable PUBLIC_URL
, there’s a special built-in environment variable called NODE_ENV
that cannot be overridden:
- When using
npm start
takes the valuedevelopment
- When using
npm run build
takes the valueproduction
- When using
npm test
takes the valuetest
You can also define custom environment variables that will be injected at build time. They must start with REACT_APP_
, otherwise, they will be ignored.
You can define them using the terminal:
#Windows set "REACT_APP_TITLE=App" && npm start #Powershell ($env:REACT_APP_TITLE = "App") -and (npm start) #Linux and mac REACT_APP_TITLE=App npm start
Or one of the following files in the root of your project (files on the left have more priority than files on the right):
- When using
npm start
:.env.development.local
,.env.development
,.env.local
,.env
- When using
npm run build
:.env.production.local
,.env.production
,.env.local
,.env
- When using
npm test
:.env.test.local
,.env.test
,.env
As hinted before, all these variables can be used with process.env
inside a component:
render() {
return (
<div>
{process.env.NODE_ENV}
</div>
);
}
Or in public/index.html
:
<title>%REACT_APP_TITLE%</title>
In addition to NODE_ENV
, there are other predefined environment variables that you can set for development settings, like BROWSER
, HOST
, and PORT
, as well as some production settings like PUBLIC_URL
and GENERATE_SOURCEMAP
.
See the complete list here.
Proxying server requests
It’s common to serve the front-end and back-end of your app in the same server and port. However, you cannot do this at development time since Create React App runs the app in its own development server.
So you have three options.
The first one is to run the back-end server on another port and make requests like this:
fetch('http://localhost:5000/endpoint')
With this approach, you need to set the CORS headers on your server.
The second one is to tell the development server to proxy any request to your back-end server by adding a proxy field to your package.json
file. For example, using:
{
...
"scripts": {
...
},
"proxy": "http://localhost:5000"
}
Instead of making a request like this:
fetch('http://localhost:5000/endpoint')
After restarting the server, you should make them like this:
fetch('/endpoint')
If this is not enough for you, a third option is to configure the proxy of each endpoint individually, like this:
{
...
"scripts": {
...
},
"proxy": {
"/api": { // Matches any request starting with /api
"target": "http://localhost:5000/api",
"timeout": 5000
...
},
"/socket": {
"target": "http://localhost:5000/api",
"ws": true // Indicate this is a WebSocket proxy.
...
}
}
}
The configuration properties are the same as the ones supported by http-proxy-middleware or http-proxy.
Configuring a progressive web app
A service worker is registered in src/index.js
. If you don’t want to enable it just remove the call to registerServiceWorker()
.
The service worker is only enabled in the production version of the application. However, if the app has already been executed, the service worker will already be installed in the browser and should be removed using unregister()
:
import { unregister } from './registerServiceWorker';
Service workers require HTTPS (otherwise registration will fail, although the app will remain functional). However, to facilitate local testing, this doesn’t apply to localhost.
A web app manifest where you can configure the app name, icons and other metadata about your application is located at public/manifest.json
.
Testing the app
Create React App uses Jest as its test runner and jsdom to provide browser global variables like window
or document
.
Test files should follow any of these naming conventions:
- If they end with
.js/.jsx/.mjs
, the files should be located in a directory named__tests__
(matching the expression<rootDir>/src/**/__tests__/**/*.{js,jsx,mjs}
) - They should end with
.test.js
or.specs.js
(matching the expression<rootDir>/src/**/?(*.)(spec|test).{js,jsx,mjs}
)
Executing npm test will run the tests by executing the script:
react-scripts test --env=jsdom
You can see the complete script here.
The tests will be run in watch mode. Every time you save a file, the tests are re-run. However, this mode also includes an interactive command-line interface with an option to enter a test name pattern to avoid running all tests.
If you just need to execute or configure something before running your tests, add it to the file src/setupTests.js
, which will be executed automatically before any test.
If you need a coverage report, you can execute the command npm test --coverage
, optionally configuring in the package.json
file the options:
- collectCoverageFrom to indicate a set of files for which coverage information should be collected.
- coverageReporters to indicate formats when writing coverage reports.
- coverageThreshold to configure minimum threshold enforcement for coverage results.
- snapshotSerializers to specify a list of paths to functions that serialize values.
For example:
{
...
"scripts": {
},
"jest": {
"coverageReporters": ["json"],
"coverageThreshold": {
"global": {
"lines": 80
}
},
}
}
Deploying the app
You can create a production version of your app in the build directory with npm run build, which is a shortcut to:
react-scripts build
You can see the complete script here.
After this, you may copy the content of this build directory to a web server or you use packages like http-server or serve to test your application from that directory.
One thing to take into account is that Create React App assumes that you will host your app at the server root. If this is not the case, you need to specify the homepage field in your package.json
file so the correct root path can be inferred:
{
...
"scripts": {
...
},
"homepage": "http://example.com/myapp"
}
However, if you are not using a router with HTML5 pushState history API or not using routing at all, you can use a dot to make sure that all the asset paths are relative to index.html:
"homepage": "."
In the user manual of Create React App, you can find instructions to deploy your app using:
Ejecting the app
Ejecting will copy all the configuration files, scripts, and dependencies to your project, while removing the dependency to react-scripts.
Execute npm run eject
to perform this operation.
Here’s an extract of the output:
And here you can see the whole script it executes.
This operation cannot be reverted. Use it when the configuration options the tool offers are not enough for you anymore.
Conclusion
This post covered the most important features you may configure when using Create React App. Now you might want to take a closer look at react-scripts, the core of Create React App, to get a deep knowledge of how it works.
Also, although Create React App is a popular tool, it is not for everyone. There might be better alternatives depending on the type of application you’re developing. For example, Gatsby for static sites or Next.js for server-side rendering. Consult more alternatives here.
Finally, here are some guides that might help you:
Full visibility into production React apps
Debugging React applications can be difficult, especially when users experience issues that are difficult to reproduce. If you’re interested in monitoring and tracking Redux state, automatically surfacing JavaScript errors, and tracking slow network requests and component load time, try LogRocket.

LogRocket is like a DVR for web apps, recording literally everything that happens on your React app. Instead of guessing why problems happen, you can aggregate and report on what state your application was in when an issue occurred. LogRocket also monitors your app's performance, reporting with metrics like client CPU load, client memory usage, and more.
The LogRocket Redux middleware package adds an extra layer of visibility into your user sessions. LogRocket logs all actions and state from your Redux stores.
Modernize how you debug your React apps — start monitoring for free.
- How to get “create-react-app” to work with your API
- Upgrading a create-react-app project to a SSR + code splitting setup
- Customizing create-react-app: How to Make Your Own Template
- Create-react-app with VS Code
- TypeScript and React using create-react-app: A step-by-step guide to setting up your first app