diff --git a/packages/react-scripts/package.json b/packages/react-scripts/package.json
index 4779f18eee18c9f96fd932e093063bed2f9e091f..e304f6e31a16e4c6d8121a5fff8fec924710320d 100644
--- a/packages/react-scripts/package.json
+++ b/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",
diff --git a/packages/react-scripts/scripts/build.js b/packages/react-scripts/scripts/build.js
index a0805e601ac38d5ba116628ae65c2677a25b2679..f8c3dda4faae1418f15cd9cdbe065019c9568ad1 100644
--- a/packages/react-scripts/scripts/build.js
+++ b/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');
diff --git a/packages/react-scripts/scripts/start.js b/packages/react-scripts/scripts/start.js
index 191631694573ad3c64cd2d14d18c382d999633b3..530e675d519e7d45874ba7f22b6479f8738aa2b2 100644
--- a/packages/react-scripts/scripts/start.js
+++ b/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');
diff --git a/packages/react-scripts/scripts/test.js b/packages/react-scripts/scripts/test.js
index d297e2d0c4cfcde8e5a29a8358902aca66e65c26..8a98aad891f40f1218fa42eadc2a30e797962c93 100644
--- a/packages/react-scripts/scripts/test.js
+++ b/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');
diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md
index 3c9952b88952bbc05faab88ddd6720b05fa95fc5..73b95584cb9ffc2fe89e292150a20cc8688b549a 100644
--- a/packages/react-scripts/template/README.md
+++ b/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?
diff --git a/packages/react-scripts/template/gitignore b/packages/react-scripts/template/gitignore
index 56b6cc8a3115537a760630a624a8b0e86d38d5fa..6c96c5cff124271309d717aa6a74c99fa3cdd455 100644
--- a/packages/react-scripts/template/gitignore
+++ b/packages/react-scripts/template/gitignore
@@ -11,4 +11,5 @@ build
# misc
.DS_Store
+.env
npm-debug.log