Brian Neville-O'Neill

Posted on Aug 1, 2018 • Originally published at blog.logrocket.com on Jul 19, 2018

Create React App: A quick setup guide

#frontenddev #webdev #javascript #react

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 likereact-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:

https://medium.com/media/8d09c1dfe8698c51b20b275d34606d75/href

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:

https://medium.com/media/824edbf058cf2c65a74f3dd5af2f5cdc/href

Or with the variable process.env.PUBLIC_URL in JavaScript:

https://medium.com/media/4f776182c834042fabccd299c9d4c1c0/href

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 value development
When using npm run build takes the value production
When using npm test takes the value test

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:

https://medium.com/media/de7b9a0067ffad0331861d3ac4312208/href

Or in public/index.html:

https://medium.com/media/10cbe804b6ac23c24a1ca1dd29eb31ec/href

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:

https://medium.com/media/f0df56e51008e5c450ff383f05aac977/href

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:

https://medium.com/media/7a25144cc3bc20eb83f38997fd7d7e04/href

Instead of making a request like this:

https://medium.com/media/f0df56e51008e5c450ff383f05aac977/href

After restarting the server, you should make them like this:

https://medium.com/media/40add1bb04912f819179cf374bd2ed70/href

If this is not enough for you, a third option is to configure the proxy of each endpoint individually, like this:

https://medium.com/media/04d7d00ede69e2fa89eb6618e5540685/href

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():

https://medium.com/media/7d6d19d3d882cb33484afddf258034e2/href

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 /src/**/__tests__/**/*.{js,jsx,mjs})
They should end with .test.js or .specs.js (matching the expression /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:

https://medium.com/media/eeabc062b44ed8fcd1c7e9d840544afc/href

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:

https://medium.com/media/ee5e5124db9fccc5d79a920ebf6dc558/href

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:

https://medium.com/media/db11303eb0bc0fafc26bccf84d6d0a12/href

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:

Plug: LogRocket, a DVR for web apps

https://logrocket.com/signup/

LogRocket is a frontend logging tool that lets you replay problems as if they happened in your own browser. Instead of guessing why errors happen, or asking users for screenshots and log dumps, LogRocket lets you replay the session to quickly understand what went wrong. It works perfectly with any app, regardless of framework, and has plugins to log additional context from Redux, Vuex, and @ngrx/store.

In addition to logging Redux actions and state, LogRocket records console logs, JavaScript errors, stacktraces, network requests/responses with headers + bodies, browser metadata, and custom logs. It also instruments the DOM to record the HTML and CSS on the page, recreating pixel-perfect videos of even the most complex single page apps.

Try it for free.

DEV Community