* Enable .env support by default Given we've had tons of reports from various people that expected .env support to work even though they had dotenv installed already I think it's fine to enable it as a default: Fixes #12728 * Remove old test * Fix duplicate env loading * Update docs Co-authored-by: JJ Kasper <jj@jjsweb.site>
4.6 KiB
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.
Next.js comes with built-in support for environment variables, which allows you to do the following:
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:
export default function Page() {
return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1>
}
Will end up being:
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 to add environment variables. For example, using bash:
NEXT_PUBLIC_EXAMPLE_KEY=my-value npx next dev
Or using cross-env for Windows and Unix support:
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. - To avoid exposing secrets, do not use the
NEXT_PUBLIC_
prefix for them. Instead, expose the variables using.env
.
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
usesdevelopment
next build
andnext start
useproduction
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:
API_KEY='my-secret-api-key'
NEXT_PUBLIC_APP_LOCALE='en-us'
And the following page:
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.
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
which runs only on the server — and only the props returned by getStaticProps
are included in the client build. Same goes for our other data fetching methods.
Now, if you add a .env
file like this one:
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.