mirror of
https://github.com/zhigang1992/create-react-app.git
synced 2026-04-23 12:48:00 +08:00
Move adding custom environment variables to its own file
This commit is contained in:
Kristofer Selbekk
161
docusaurus/docs/adding-custom-environment-variables.md
Normal file
161
docusaurus/docs/adding-custom-environment-variables.md
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: adding-custom-environment-variables
|
||||
title: Adding Custom Environment Variables
|
||||
---
|
||||
> Note: this feature is available with `react-scripts@0.2.3` and higher.
|
||||
|
||||
Your project can consume variables declared in your environment as if they were declared locally in your JS files. By
|
||||
default you will have `NODE_ENV` defined for you, and any other environment variables starting with
|
||||
`REACT_APP_`.
|
||||
|
||||
**The environment variables are embedded during the build time**. Since Create React App produces a static HTML/CSS/JS bundle, it can’t possibly read them at runtime. To read them at runtime, you would need to load HTML into memory on the server and replace placeholders in runtime, just like [described here](#injecting-data-from-the-server-into-the-page). Alternatively you can rebuild the app on the server anytime you change them.
|
||||
|
||||
> Note: You must create custom environment variables beginning with `REACT_APP_`. Any other variables except `NODE_ENV` will be ignored to avoid accidentally [exposing a private key on the machine that could have the same name](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527). Changing any environment variables will require you to restart the development server if it is running.
|
||||
|
||||
These environment variables will be defined for you on `process.env`. For example, having an environment
|
||||
variable named `REACT_APP_SECRET_CODE` will be exposed in your JS as `process.env.REACT_APP_SECRET_CODE`.
|
||||
|
||||
There is also a special built-in environment variable called `NODE_ENV`. You can read it from `process.env.NODE_ENV`. When you run `npm start`, it is always equal to `'development'`, when you run `npm test` it is always equal to `'test'`, and when you run `npm run build` to make a production bundle, it is always equal to `'production'`. **You cannot override `NODE_ENV` manually.** This prevents developers from accidentally deploying a slow development build to production.
|
||||
|
||||
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. For example, let’s say you wanted to consume a secret defined
|
||||
in the environment inside a `<form>`:
|
||||
|
||||
```jsx
|
||||
render() {
|
||||
return (
|
||||
<div>
|
||||
<small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small>
|
||||
<form>
|
||||
<input type="hidden" defaultValue={process.env.REACT_APP_SECRET_CODE} />
|
||||
</form>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
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. This can be done using two ways: either in your shell or in
|
||||
a `.env` file. Both of these ways are described in the next few sections.
|
||||
|
||||
Having access to the `NODE_ENV` is also useful for performing actions conditionally:
|
||||
|
||||
```js
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
analytics.disable();
|
||||
}
|
||||
```
|
||||
|
||||
When you compile the app with `npm run build`, the minification step will strip out this condition, and the resulting bundle will be smaller.
|
||||
|
||||
### Referencing Environment Variables in the HTML
|
||||
|
||||
> Note: this feature is available with `react-scripts@0.9.0` and higher.
|
||||
|
||||
You can also access the environment variables starting with `REACT_APP_` in the `public/index.html`. For example:
|
||||
|
||||
```html
|
||||
<title>%REACT_APP_WEBSITE_NAME%</title>
|
||||
```
|
||||
|
||||
Note that the caveats from the above section apply:
|
||||
|
||||
- Apart from a few built-in variables (`NODE_ENV` and `PUBLIC_URL`), variable names must start with `REACT_APP_` to work.
|
||||
- The environment variables are injected at build time. If you need to inject them at runtime, [follow this approach instead](#generating-dynamic-meta-tags-on-the-server).
|
||||
|
||||
### 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)
|
||||
|
||||
```cmd
|
||||
set "REACT_APP_SECRET_CODE=abcdef" && npm start
|
||||
```
|
||||
|
||||
(Note: Quotes around the variable assignment are required to avoid a trailing whitespace.)
|
||||
|
||||
#### Windows (Powershell)
|
||||
|
||||
```Powershell
|
||||
($env:REACT_APP_SECRET_CODE = "abcdef") -and (npm start)
|
||||
```
|
||||
|
||||
#### Linux, macOS (Bash)
|
||||
|
||||
```bash
|
||||
REACT_APP_SECRET_CODE=abcdef npm start
|
||||
```
|
||||
|
||||
### Adding Development Environment Variables In `.env`
|
||||
|
||||
> Note: this feature is available with `react-scripts@0.5.0` and higher.
|
||||
|
||||
To define permanent environment variables, create a file called `.env` in the root of your project:
|
||||
|
||||
```
|
||||
REACT_APP_SECRET_CODE=abcdef
|
||||
```
|
||||
|
||||
> Note: You must create custom environment variables beginning with `REACT_APP_`. Any other variables except `NODE_ENV` will be ignored to avoid [accidentally exposing a private key on the machine that could have the same name](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527). Changing any environment variables will require you to restart the development server if it is running.
|
||||
|
||||
`.env` files **should be** checked into source control (with the exclusion of `.env*.local`).
|
||||
|
||||
#### What other `.env` files can be used?
|
||||
|
||||
> Note: this feature is **available with `react-scripts@1.0.0` and higher**.
|
||||
|
||||
- `.env`: Default.
|
||||
- `.env.local`: Local overrides. **This file is loaded for all environments except test.**
|
||||
- `.env.development`, `.env.test`, `.env.production`: Environment-specific settings.
|
||||
- `.env.development.local`, `.env.test.local`, `.env.production.local`: Local overrides of environment-specific settings.
|
||||
|
||||
Files on the left have more priority than files on the right:
|
||||
|
||||
- `npm start`: `.env.development.local`, `.env.development`, `.env.local`, `.env`
|
||||
- `npm run build`: `.env.production.local`, `.env.production`, `.env.local`, `.env`
|
||||
- `npm test`: `.env.test.local`, `.env.test`, `.env` (note `.env.local` is missing)
|
||||
|
||||
These variables will act as the defaults if the machine does not explicitly set them.<br>
|
||||
Please refer to the [dotenv documentation](https://github.com/motdotla/dotenv) for more details.
|
||||
|
||||
> 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).
|
||||
|
||||
#### Expanding Environment Variables In `.env`
|
||||
|
||||
> Note: this feature is available with `react-scripts@1.1.0` and higher.
|
||||
|
||||
Expand variables already on your machine for use in your `.env` file (using [dotenv-expand](https://github.com/motdotla/dotenv-expand)).
|
||||
|
||||
For example, to get the environment variable `npm_package_version`:
|
||||
|
||||
```
|
||||
REACT_APP_VERSION=$npm_package_version
|
||||
# also works:
|
||||
# REACT_APP_VERSION=${npm_package_version}
|
||||
```
|
||||
|
||||
Or expand variables local to the current `.env` file:
|
||||
|
||||
```
|
||||
DOMAIN=www.example.com
|
||||
REACT_APP_FOO=$DOMAIN/foo
|
||||
REACT_APP_BAR=$DOMAIN/bar
|
||||
```
|
||||
@@ -11,10 +11,6 @@ You can find the most recent version of this guide [here](https://github.com/fac
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Adding Custom Environment Variables](#adding-custom-environment-variables)
|
||||
- [Referencing Environment Variables in the HTML](#referencing-environment-variables-in-the-html)
|
||||
- [Adding Temporary Environment Variables In Your Shell](#adding-temporary-environment-variables-in-your-shell)
|
||||
- [Adding Development Environment Variables In `.env`](#adding-development-environment-variables-in-env)
|
||||
- [Can I Use Decorators?](#can-i-use-decorators)
|
||||
- [Fetching Data with AJAX Requests](#fetching-data-with-ajax-requests)
|
||||
- [Integrating with an API Backend](#integrating-with-an-api-backend)
|
||||
@@ -31,166 +27,6 @@ You can find the most recent version of this guide [here](https://github.com/fac
|
||||
- [Advanced Configuration](#advanced-configuration)
|
||||
- [Alternatives to Ejecting](#alternatives-to-ejecting)
|
||||
|
||||
## Adding Custom Environment Variables
|
||||
|
||||
> Note: this feature is available with `react-scripts@0.2.3` and higher.
|
||||
|
||||
Your project can consume variables declared in your environment as if they were declared locally in your JS files. By
|
||||
default you will have `NODE_ENV` defined for you, and any other environment variables starting with
|
||||
`REACT_APP_`.
|
||||
|
||||
**The environment variables are embedded during the build time**. Since Create React App produces a static HTML/CSS/JS bundle, it can’t possibly read them at runtime. To read them at runtime, you would need to load HTML into memory on the server and replace placeholders in runtime, just like [described here](#injecting-data-from-the-server-into-the-page). Alternatively you can rebuild the app on the server anytime you change them.
|
||||
|
||||
> Note: You must create custom environment variables beginning with `REACT_APP_`. Any other variables except `NODE_ENV` will be ignored to avoid accidentally [exposing a private key on the machine that could have the same name](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527). Changing any environment variables will require you to restart the development server if it is running.
|
||||
|
||||
These environment variables will be defined for you on `process.env`. For example, having an environment
|
||||
variable named `REACT_APP_SECRET_CODE` will be exposed in your JS as `process.env.REACT_APP_SECRET_CODE`.
|
||||
|
||||
There is also a special built-in environment variable called `NODE_ENV`. You can read it from `process.env.NODE_ENV`. When you run `npm start`, it is always equal to `'development'`, when you run `npm test` it is always equal to `'test'`, and when you run `npm run build` to make a production bundle, it is always equal to `'production'`. **You cannot override `NODE_ENV` manually.** This prevents developers from accidentally deploying a slow development build to production.
|
||||
|
||||
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. For example, let’s say you wanted to consume a secret defined
|
||||
in the environment inside a `<form>`:
|
||||
|
||||
```jsx
|
||||
render() {
|
||||
return (
|
||||
<div>
|
||||
<small>You are running this application in <b>{process.env.NODE_ENV}</b> mode.</small>
|
||||
<form>
|
||||
<input type="hidden" defaultValue={process.env.REACT_APP_SECRET_CODE} />
|
||||
</form>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
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>
|
||||
```
|
||||
|
||||
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. This can be done using two ways: either in your shell or in
|
||||
a `.env` file. Both of these ways are described in the next few sections.
|
||||
|
||||
Having access to the `NODE_ENV` is also useful for performing actions conditionally:
|
||||
|
||||
```js
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
analytics.disable();
|
||||
}
|
||||
```
|
||||
|
||||
When you compile the app with `npm run build`, the minification step will strip out this condition, and the resulting bundle will be smaller.
|
||||
|
||||
### Referencing Environment Variables in the HTML
|
||||
|
||||
> Note: this feature is available with `react-scripts@0.9.0` and higher.
|
||||
|
||||
You can also access the environment variables starting with `REACT_APP_` in the `public/index.html`. For example:
|
||||
|
||||
```html
|
||||
<title>%REACT_APP_WEBSITE_NAME%</title>
|
||||
```
|
||||
|
||||
Note that the caveats from the above section apply:
|
||||
|
||||
- Apart from a few built-in variables (`NODE_ENV` and `PUBLIC_URL`), variable names must start with `REACT_APP_` to work.
|
||||
- The environment variables are injected at build time. If you need to inject them at runtime, [follow this approach instead](#generating-dynamic-meta-tags-on-the-server).
|
||||
|
||||
### 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)
|
||||
|
||||
```cmd
|
||||
set "REACT_APP_SECRET_CODE=abcdef" && npm start
|
||||
```
|
||||
|
||||
(Note: Quotes around the variable assignment are required to avoid a trailing whitespace.)
|
||||
|
||||
#### Windows (Powershell)
|
||||
|
||||
```Powershell
|
||||
($env:REACT_APP_SECRET_CODE = "abcdef") -and (npm start)
|
||||
```
|
||||
|
||||
#### Linux, macOS (Bash)
|
||||
|
||||
```bash
|
||||
REACT_APP_SECRET_CODE=abcdef npm start
|
||||
```
|
||||
|
||||
### Adding Development Environment Variables In `.env`
|
||||
|
||||
> Note: this feature is available with `react-scripts@0.5.0` and higher.
|
||||
|
||||
To define permanent environment variables, create a file called `.env` in the root of your project:
|
||||
|
||||
```
|
||||
REACT_APP_SECRET_CODE=abcdef
|
||||
```
|
||||
|
||||
> Note: You must create custom environment variables beginning with `REACT_APP_`. Any other variables except `NODE_ENV` will be ignored to avoid [accidentally exposing a private key on the machine that could have the same name](https://github.com/facebook/create-react-app/issues/865#issuecomment-252199527). Changing any environment variables will require you to restart the development server if it is running.
|
||||
|
||||
`.env` files **should be** checked into source control (with the exclusion of `.env*.local`).
|
||||
|
||||
#### What other `.env` files can be used?
|
||||
|
||||
> Note: this feature is **available with `react-scripts@1.0.0` and higher**.
|
||||
|
||||
- `.env`: Default.
|
||||
- `.env.local`: Local overrides. **This file is loaded for all environments except test.**
|
||||
- `.env.development`, `.env.test`, `.env.production`: Environment-specific settings.
|
||||
- `.env.development.local`, `.env.test.local`, `.env.production.local`: Local overrides of environment-specific settings.
|
||||
|
||||
Files on the left have more priority than files on the right:
|
||||
|
||||
- `npm start`: `.env.development.local`, `.env.development`, `.env.local`, `.env`
|
||||
- `npm run build`: `.env.production.local`, `.env.production`, `.env.local`, `.env`
|
||||
- `npm test`: `.env.test.local`, `.env.test`, `.env` (note `.env.local` is missing)
|
||||
|
||||
These variables will act as the defaults if the machine does not explicitly set them.<br>
|
||||
Please refer to the [dotenv documentation](https://github.com/motdotla/dotenv) for more details.
|
||||
|
||||
> 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).
|
||||
|
||||
#### Expanding Environment Variables In `.env`
|
||||
|
||||
> Note: this feature is available with `react-scripts@1.1.0` and higher.
|
||||
|
||||
Expand variables already on your machine for use in your `.env` file (using [dotenv-expand](https://github.com/motdotla/dotenv-expand)).
|
||||
|
||||
For example, to get the environment variable `npm_package_version`:
|
||||
|
||||
```
|
||||
REACT_APP_VERSION=$npm_package_version
|
||||
# also works:
|
||||
# REACT_APP_VERSION=${npm_package_version}
|
||||
```
|
||||
|
||||
Or expand variables local to the current `.env` file:
|
||||
|
||||
```
|
||||
DOMAIN=www.example.com
|
||||
REACT_APP_FOO=$DOMAIN/foo
|
||||
REACT_APP_BAR=$DOMAIN/bar
|
||||
```
|
||||
|
||||
## Can I Use Decorators?
|
||||
|
||||
Some popular libraries use [decorators](https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841) in their documentation.<br>
|
||||
|
||||
@@ -31,7 +31,8 @@
|
||||
"adding-bootstrap",
|
||||
"adding-flow",
|
||||
"adding-relay",
|
||||
"adding-a-router"
|
||||
"adding-a-router",
|
||||
"adding-custom-environment-variables"
|
||||
],
|
||||
"Testing": ["running-tests", "debugging-tests"],
|
||||
"Deployment": ["publishing-components-to-npm", "deployment"],
|
||||
|
||||
Reference in New Issue
Block a user