Load environment file in development (#695)

* Load environment file via dotenv if .env file is present

* Document loading environment variables in .env file

* Minor doc tweaks

packages/react-scripts/package.json

@@ -34,6 +34,7 @@
     "cross-spawn": "4.0.0",
     "css-loader": "0.24.0",
     "detect-port": "1.0.0",
+    "dotenv": "2.0.0",
     "eslint": "3.5.0",
     "eslint-config-react-app": "0.2.0",
     "eslint-loader": "1.5.0",

packages/react-scripts/scripts/build.js

@@ -12,6 +12,12 @@
 // Do this as the first thing so that any code reading it knows the right env.
 process.env.NODE_ENV = 'production';
 
+// Load environment variables from .env file. Surpress warnings using silent
+// if this file is missing. dotenv will never modify any environment variables
+// that have already been set.
+// https://github.com/motdotla/dotenv
+require('dotenv').config({silent: true});
+
 var chalk = require('chalk');
 var fs = require('fs-extra');
 var path = require('path');

packages/react-scripts/scripts/start.js

@@ -11,6 +11,12 @@
 
 process.env.NODE_ENV = 'development';
 
+// Load environment variables from .env file. Surpress warnings using silent
+// if this file is missing. dotenv will never modify any environment variables
+// that have already been set.
+// https://github.com/motdotla/dotenv
+require('dotenv').config({silent: true});
+
 var path = require('path');
 var chalk = require('chalk');
 var webpack = require('webpack');

packages/react-scripts/scripts/test.js

@@ -10,6 +10,12 @@
 process.env.NODE_ENV = 'test';
 process.env.PUBLIC_URL = '';
 
+// Load environment variables from .env file. Surpress warnings using silent
+// if this file is missing. dotenv will never modify any environment variables
+// that have already been set.
+// https://github.com/motdotla/dotenv
+require('dotenv').config({silent: true});
+
 const createJestConfig = require('./utils/createJestConfig');
 const jest = require('jest');
 const path = require('path');

packages/react-scripts/template/README.md

@@ -400,8 +400,8 @@ to `process.env.NODE_ENV`.
 These environment variables can be useful for displaying information conditionally based on where the project is
 deployed or consuming sensitive data that lives outside of version control.
 
-First, you need to have environment variables defined, which can vary between OSes. For example, let's say you wanted to
-consume a secret defined in the environment inside a `<form>`:
+First, you need to have environment variables defined. For example, let’s say you wanted to consume a secret defined
+in the environment inside a `<form>`:
 
 ```jsx
 render() {
@@ -416,8 +416,35 @@ render() {
 }
 ```
 
+During the build, `process.env.REACT_APP_SECRET_CODE` will be replaced with the current value of the `REACT_APP_SECRET_CODE` environment variable. Remember that the `NODE_ENV` variable will be set for you automatically.
+
+When you load the app in the browser and inspect the `<input>`, you will see its value set to `abcdef`, and the bold text will show the environment provided when using `npm start`:
+
+```html
+<div>
+  <small>You are running this application in <b>development</b> mode.</small>
+  <form>
+    <input type="hidden" value="abcdef" />
+  </form>
+</div>
+```
+
+Having access to the `NODE_ENV` is also useful for performing actions conditionally:
+
+```js
+if (process.env.NODE_ENV !== 'production') {
+  analytics.disable();
+}
+```
+
 The above form is looking for a variable called `REACT_APP_SECRET_CODE` from the environment. In order to consume this
-value, we need to have it defined in the environment:
+value, we need to have it defined in the environment. This can be done using two ways: either in your shell or in
+a `.env` file.
+
+### Adding Temporary Environment Variables In Your Shell
+
+Defining environment variables can vary between OSes. It's also important to know that this manner is temporary for the
+life of the shell session.
 
 #### Windows (cmd.exe)
 
@@ -433,29 +460,21 @@ set REACT_APP_SECRET_CODE=abcdef&&npm start
 REACT_APP_SECRET_CODE=abcdef npm start
 ```
 
-> Note: Defining environment variables in this manner is temporary for the life of the shell session. Setting
-permanent environment variables is outside the scope of these docs.
+### Adding Development Environment Variables In `.env`
 
-With our environment variable defined, we start the app and consume the values. Remember that the `NODE_ENV`
-variable will be set for you automatically. When you load the app in the browser and inspect the `<input>`, you will see
-its value set to `abcdef`, and the bold text will show the environment provided when using `npm start`:
+>Note: this feature is available with `react-scripts@0.5.0` and higher.
 
-```html
-<div>
-  <small>You are running this application in <b>development</b> mode.</small>
-  <form>
-    <input type="hidden" value="abcdef" />
-  </form>
-</div>
+To define permanent environment vairables, create a file called `.env` in the root of your project:
+
+```
+REACT_APP_SECRET_CODE=abcdef
 ```
 
-Having access to the `NODE_ENV` is also useful for performing actions conditionally:
+These variables will act as the defaults if the machine does not explicitly set them.  
+Please refer to the [dotenv documentation](https://github.com/motdotla/dotenv) for more details.
 
-```js
-if (process.env.NODE_ENV !== 'production') {
-  analytics.disable();
-}
-```
+>Note: If you are defining environment variables for development, your CI and/or hosting platform will most likely need
+these defined as well. Consult their documentation how to do this. For example, see the documentation for [Travis CI](https://docs.travis-ci.com/user/environment-variables/) or [Heroku](https://devcenter.heroku.com/articles/config-vars).
 
 ## Can I Use Decorators?
 

packages/react-scripts/template/gitignore

@@ -11,4 +11,5 @@ build
 
 # misc
 .DS_Store
+.env
 npm-debug.log