Starting a new React project nowadays is not as simple as we’d like it to be. Instead of instantly diving into the code and bringing your application to life, you have to spend time configuring the right build tools to set up a local development environment, unit testing, and a production build. But there are projects where all you need is a simple setup to get things running quickly and with minimal effort.
Create React App provides just that. It’s a CLI tool from Facebook that allows you to generate a new React project and use a pre-configured Webpack build for development. Using it, you’ll never have to look at the Webpack config again.
How Does Create React App Work?
Create React App is a standalone tool that should be installed globally via npm, and called each time you need to create a new project:
npm install -g create-react-app
To create a new project, run:
Create React App will set up the following project structure:
. ├── .gitignore ├── README.md ├── package.json ├── node_modules ├── public │ ├── favicon.ico │ └── index.html └── src ├── App.css ├── App.js ├── App.test.js ├── index.css ├── index.js └── logo.svg
It will also add a
react-scripts package to your project that will contain all of the configuration and build scripts. In other words, your project depends
react-scripts, not on
create-react-app itself. Once the installation is complete, you can start working on your project.
Starting a Local Development Server
The first thing you’ll need is a local development environment. Running
npm start will fire up a Webpack development server with a watcher that will automatically reload the application once you change something. Hot reloading, however, is only supported for styles.
The application will be generated with a number of features built-in.
ES6 and ES7
The application comes with its own Babel preset, babel-preset-react-app, to support a set of ES6 and ES7 features. It even supports some of the newer features like async/await, and import/export statements. However, certain features, like decorators, have been intentionally left out.
You can also import CSS files from your JS modules that allow you to bundle styles that are only relevant for the modules that you ship. The same thing can be done for images and fonts.
During development, your code will also be run through ESLint, a static code analyzer that will help you spot errors during development.
You can use Node environment variables to inject values into your code at built-time. React-scripts will automatically look for any environment variables starting with
REACT_APP_ and make them available under the global
process.env. These variables can be in a
.env file for convenience:
You can then reference them in your code:
Proxying to a backend
If your application will be working with a remote backend, you might need to be able to proxy requests during local development to bypass CORS. This can be set up by adding a proxy field to your
This way, the server will forward any request that doesn’t point to a static file the given address.
Running Unit Tests
npm test will run tests using Jest and start a watcher to re-run them whenever you change something:
PASS src/App.test.js ✓ renders without crashing (7ms) Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total Time: 0.123s, estimated 1s Ran all test suites. Watch Usage › Press p to filter by a filename regex pattern. › Press q to quit watch mode. › Press Enter to trigger a test run.
Jest is a test runner also developed by Facebook as an alternative to Mocha or Karma. It runs the tests on a Node environment instead of a real browser, but provides some of the browser-specific globals using jsdom.
Jest also comes integrated with your VCS and by default will only run tests on files changed since your last commit. For more on this, refer to “How to Test React Components Using Jest”.
Creating a Production Bundle
When you finally have something you deploy, you can create a production bundle using
npm run build. This will generate an optimized build of your application, ready to be deployed to your environment. The generated artifacts will be placed in the build folder:
. ├── asset-manifest.json ├── favicon.ico ├── index.html └── static ├── css │ ├── main.9a0fe4f1.css │ └── main.9a0fe4f1.css.map ├── js │ ├── main.3b7bfee7.js │ └── main.3b7bfee7.js.map └── media └── logo.5d5d9eef.svg
React-scripts provides a way to deploy your application to GitHub pages by simply adding a homepage property to
package.json. There’s also a separate Heroku build pack.
If at some point you feel that the features provided are no longer enough for your project, you can always opt out of using react-scripts by running
npm run eject. This will copy the Webpack configuration and build scripts from
react-scripts into your project and remove the dependency. After that, you’re free to modify the configuration however you see fit.
If you’re looking to start a new React project look no further. Create React App will allow you to quickly start working on your application instead of writing yet another Webpack config.
Have you given it a try yet? What did you think? Let me know in the comments!
This post was peer reviewed by Joan Yin. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!