108 lines
4.9 KiB
Markdown
108 lines
4.9 KiB
Markdown
---
|
||
description: Learn to add and access environment variables in your Next.js application.
|
||
---
|
||
|
||
# Environment Variables
|
||
|
||
> This document is for Next.js versions 9.4 and up. If you’re using an older version of Next.js, refer to [Environment Variables in next.config.js](/docs/api-reference/next.config.js/environment-variables.md).
|
||
|
||
Next.js comes with built-in support for environment variables, which allows you to do the following:
|
||
|
||
- [Inline variables starting with `NEXT_PUBLIC_`](#inlined-environment-variables)
|
||
- [Use `.env` to add custom environment variables](#exposing-environment-variables)
|
||
|
||
## Inlined Environment Variables
|
||
|
||
Next.js will inline any environment variable that starts with `NEXT_PUBLIC_` in your application. Inlining means replacing the variable with the value. For example, the following page:
|
||
|
||
```jsx
|
||
export default function Page() {
|
||
return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1>
|
||
}
|
||
```
|
||
|
||
Will end up being:
|
||
|
||
```jsx
|
||
export default function Page() {
|
||
return <h1>The public value is: {'my-value'}</h1>
|
||
}
|
||
```
|
||
|
||
Next.js replaced `process.env.NEXT_PUBLIC_EXAMPLE_KEY` with its value, that in this case is `'my-value'`.
|
||
|
||
You can use the shell or any other tool that runs before the [Next.js CLI](/api-reference/cli) to add environment variables. For example, using bash:
|
||
|
||
```bash
|
||
NEXT_PUBLIC_EXAMPLE_KEY=my-value npx next dev
|
||
```
|
||
|
||
Or using [cross-env](https://github.com/kentcdodds/cross-env) for Windows and Unix support:
|
||
|
||
```bash
|
||
npx cross-env NEXT_PUBLIC_EXAMPLE_KEY=my-value next dev
|
||
```
|
||
|
||
### Caveats
|
||
|
||
- Trying to destructure `process.env` variables won't work due to the limitations of webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/).
|
||
- To avoid exposing secrets, do not use the `NEXT_PUBLIC_` prefix for them. Instead, [expose the variables using `.env`](#exposing-environment-variables).
|
||
- You cannot have `dotenv` installed in your project, as this will cause Next.js to disable the auto-loading of the environment variables. Look for and uninstall this package if your variables are showing up as `undefined`.
|
||
|
||
## Exposing Environment Variables
|
||
|
||
Next.js allows you to expose variables using an environment variables file (`.env`), with included support for multiple environments. It works like this:
|
||
|
||
- `.env` - Contains environment variables for all environments
|
||
- `.env.local` - Local variable overrides for all environments
|
||
- `.env.[environment]` - Environment variables for one environment. For example: `.env.development`
|
||
- `.env.[environment].local` - Local variable overrides for one environment. For example: `.env.development.local`
|
||
|
||
> **Note**: `.env` files **should be** included in your repository, and **`.env*.local` should be in `.gitignore`**, as those files are intended to be ignored. Consider `.local` files as a good place for secrets, and non-local files as a good place for defaults.
|
||
|
||
The supported environments are `development`, `production` and `test`. The environment is selected in the following way:
|
||
|
||
- [`next dev`](/docs/api-reference/cli#development) uses `development`
|
||
- [`next build`](/docs/api-reference/cli#build) and [`next start`](/docs/api-reference/cli#production) use `production`
|
||
|
||
If the same environment variable is defined multiple times, the priority of which variable to use is decided in the following order:
|
||
|
||
- Already defined environment variables have the higher priority. For example: `MY_KEY=value next dev`
|
||
- `.env.[environment].local`
|
||
- `.env.[environment]`
|
||
- `.env.local`
|
||
- `.env`
|
||
|
||
For example, consider the file `.env.local` with the following content:
|
||
|
||
```bash
|
||
API_KEY='my-secret-api-key'
|
||
NEXT_PUBLIC_APP_LOCALE='en-us'
|
||
```
|
||
|
||
And the following page:
|
||
|
||
```jsx
|
||
export default function Page() {
|
||
return <h1>The locale is set to: {process.env.NEXT_PUBLIC_APP_LOCALE}</h1>
|
||
}
|
||
|
||
export async function getStaticProps() {
|
||
const db = await myDB(process.env.API_KEY)
|
||
// ...
|
||
}
|
||
```
|
||
|
||
`process.env.NEXT_PUBLIC_APP_LOCALE` will be replaced with `'en-us'` in the build output. This is because variables that start with `NEXT_PUBLIC_` will be [inlined at build time](#inlined-environment-variables).
|
||
|
||
`process.env.API_KEY` will be a variable with `'my-secret-api-key'` at build time and runtime, but the build output will not contain this key. This is because `process.env.API_KEY` is only used by [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) which [runs only on the server](/docs/basic-features/data-fetching.md#write-server-side-code-directly) — and only the props returned by `getStaticProps` are included in the client build. Same goes for our other [data fetching methods](/docs/basic-features/data-fetching.md).
|
||
|
||
Now, if you add a `.env` file like this one:
|
||
|
||
```bash
|
||
API_KEY='default-api-key'
|
||
CLIENT_KEY='default-client-key'
|
||
NEXT_PUBLIC_APP_LOCALE='en-us'
|
||
```
|
||
|
||
Both `API_KEY` and `NEXT_PUBLIC_APP_LOCALE` will be ignored as `.env.local` has a higher priority, but `CLIENT_KEY` will become available.
|