Unverified Commit c384ca37 authored by Tim Neutkens's avatar Tim Neutkens Committed by GitHub

Update environment variables documentation (#13618)

Based on feedback from @mcsdevv's team. Solves many of the issues users run into with the current docs.
parent 3dc24bbd
...@@ -4,104 +4,87 @@ description: Learn to add and access environment variables in your Next.js appli ...@@ -4,104 +4,87 @@ description: Learn to add and access environment variables in your Next.js appli
# Environment Variables # 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). > This document is for Next.js versions 9.4 and up. If you’re using an older version of Next.js, upgrade or 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: 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) - [Inline variables starting with `NEXT_PUBLIC_`](#inlined-environment-variables)
- [Use `.env` to add custom environment variables](#exposing-environment-variables) - [Use `.env` to add custom environment variables](#exposing-environment-variables)
## Inlined Environment Variables ## Loading 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: Next.js has built-in support for loading environment variables from `.env.local` into `process.env`.
```jsx An example `.env.local`:
export default function Page() {
return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1> ```bash
} # .env.local
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword
``` ```
Will end up being: This loads `process.env.DB_HOST`, `process.env.DB_USER`, and `process.env.DB_PASS` into the Node.js environment automatically allowing you to use them in `getStaticProps`, `getStaticPaths`, `getServerSideProps`, and API routes.
```jsx For example using `getStaticProps`:
export default function Page() {
return <h1>The public value is: {'my-value'}</h1> ```js
// pages/index.js
export async function getStaticProps() {
const db = await myDB.connect({
host: process.env.DB_HOST,
username: process.env.DB_USER,
password: process.env.DB_PASS,
})
// ...
} }
``` ```
Next.js replaced `process.env.NEXT_PUBLIC_EXAMPLE_KEY` with its value, that in this case is `'my-value'`. ## Exposing Environment Variables to the Browser
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: By default all environment variables loaded through `.env.local` are only available in the Node.js environment, meaning they won't be exposed to the browser.
```bash In order to expose a variable to the browser you can prefix the variable with `NEXT_PUBLIC_`. For example:
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 ```bash
npx cross-env NEXT_PUBLIC_EXAMPLE_KEY=my-value next dev # .env.local
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk
``` ```
### Caveats This loads `process.env.NEXT_PUBLIC_ANALYTICS_ID` into the Node.js environment automatically. Allowing you to use it anywhere in your code. The value will be inlined into JavaScript sent to the browser because of the `NEXT_PUBLIC_` prefix.
- 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).
## 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 ```js
- `.env.local` - Local variable overrides for all environments // pages/index.js
- `.env.[environment]` - Environment variables for one environment. For example: `.env.development` import setupAnalyticsService from '../lib/my-analytics-service'
- `.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. // NEXT_PUBLIC_ANALYTICS_ID can be used here as it's prefixed by NEXT_PUBLIC_
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
The supported environments are `development`, `production` and `test`. The environment is selected in the following way: function HomePage() {
return <h1>Hello World</h1>
}
- [`next dev`](/docs/api-reference/cli#development) uses `development` export default HomePage
- [`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: ## Default Environment Variables
- Already defined environment variables have the higher priority. For example: `MY_KEY=value next dev` In general only one `.env.local` file is needed. However, sometimes you might want to add some defaults for the `development` (`next dev`) or `production` (`next start`) environment.
- `.env.[environment].local`
- `.env.local`
- `.env.[environment]`
- `.env`
For example, consider the file `.env.local` with the following content: Next.js allows you to set defaults in `.env` (all environments), `.env.development` (development environment), and `.env.production` (production environment).
```bash `.env.local` always overrides the defaults set.
API_KEY='my-secret-api-key'
NEXT_PUBLIC_APP_LOCALE='en-us'
```
And the following page: > **Note**: `.env`, `.env.development`, and `.env.production` files should be included in your repository as they define defaults. **`.env*.local` should be added to `.gitignore`**, as those files are intended to be ignored. `.env.local` is where secrets can be stored
```jsx ## Environment Variables on Vercel
export default function Page() {
return <h1>The locale is set to: {process.env.NEXT_PUBLIC_APP_LOCALE}</h1>
}
export async function getStaticProps() { When deploying on [Vercel](https://vercel.com) you can configure secrets in the [Environment Variables](https://vercel.com/docs/v2/build-step#environment-variables) section of the project in the Vercel dashboard.
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). You can still use `.env`, `.env.development` and `.env.production` to add defaults.
`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). If you've configured [Development Environment Variables](https://vercel.com/docs/v2/build-step#development-environment-variables) you can pull them into a `.env.local` for usage on your local machine using the following command:
Now, if you add a `.env` file like this one:
```bash ```bash
API_KEY='default-api-key' vercel env pull .env.local
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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment