Document multiple build environments via env-cmd #4071

packages/react-scripts/template/README.md

@@ -2196,6 +2196,67 @@ If you are not using the HTML5 `pushState` history API or not using client-side
 
 This will make sure that all the asset paths are relative to `index.html`. You will then be able to move your app from `http://mywebsite.com` to `http://mywebsite.com/relativepath` or even `http://mywebsite.com/relative/path` without having to rebuild it.
 
+#### Building for Multiple Environments
+
+Applications are generally split between different environments such as staging, production, and development. To allow the app to run in these different environments one must set environment variables to be able to conditionally run different processes depending on the specified environment.
+
+`create-react-app` handles environment variables in a specific way. [Adding Custom Environment Variables](https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-custom-environment-variables)
+
+1. You cannot override `NODE_ENV`, it is always set to `'production'`
+
+2. It is mandated that you prefix any custom environment variables with `REACT_APP_`
+
+    - This means you cannot run:
+
+      - `NODE_ENV=staging npm run build`
+
+    - But you can run:
+
+      - `REACT_APP_NODE_ENV=staging npm run build`
+
+When the environment variable is set you can then do conditionals within your code:
+
+```js
+if (process.env.REACT_APP_NODE_ENV === 'staging') {
+    analytics.setEnvironment('staging');
+}
+```
+
+Though, you should write this command within your `package.json` :
+
+```js
+{
+  // ...
+  "scripts": {
+    "build:staging": "REACT_APP_NODE_ENV=staging npm run build",
+    // ...
+  }
+  // ...
+}
+```
+
+But, the ideal way is to use `.env` files as you can specify many environment variables simultaneously. This can be done as so:
+
+Within `.env.staging` write this:
+
+`REACT_APP_NODE_ENV=staging`
+
+and within your `package.json`:
+
+```js
+{
+  // ...
+  "scripts": {
+    "build:staging": "env-cmd .env.staging npm run build",
+    // ...
+  }
+  // ...
+}
+```
+Then run `npm run build:staging`
+
+You may use `.env.production` as the fallback option in this case as `'production'` is the default `NODE_ENV`
+
 ### [Azure](https://azure.microsoft.com/)
 
 See [this](https://medium.com/@to_pe/deploying-create-react-app-on-microsoft-azure-c0f6686a4321) blog post on how to deploy your React app to Microsoft Azure.