\n\nThis 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.
\n
Next.js comes with built-in support for environment variables, which allows you to do the following:
\n\nNext.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() {\n return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1>\n}\nWill end up being:
\nexport default function Page() {\n return <h1>The public value is: {'my-value'}</h1>\n}\nNext.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:
\nNEXT_PUBLIC_EXAMPLE_KEY=my-value npx next dev\nOr using cross-env for Windows and Unix support:
\nnpx cross-env NEXT_PUBLIC_EXAMPLE_KEY=my-value next dev\nprocess.env variables won't work due to the limitations of webpack's DefinePlugin.NEXT_PUBLIC_ prefix for them. Instead, expose the variables using .env.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\n\nNote:
\n.envfiles should be included in your repository, and.env*.localshould be in.gitignore, as those files are intended to be ignored. Consider.localfiles 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 uses developmentnext build and next start use productionIf the same environment variable is defined multiple times, the priority of which variable to use is decided in the following order:
\nMY_KEY=value next dev.env.[environment].local.env.[environment].env.local.envFor example, consider the file .env.local with the following content:
API_KEY='my-secret-api-key'\nNEXT_PUBLIC_APP_LOCALE='en-us'\nAnd the following page:
\nexport default function Page() {\n return <h1>The locale is set to: {process.env.NEXT_PUBLIC_APP_LOCALE}</h1>\n}\n\nexport async function getStaticProps() {\n const db = await myDB(process.env.API_KEY)\n // ...\n}\nprocess.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'\nCLIENT_KEY='default-client-key'\nNEXT_PUBLIC_APP_LOCALE='en-us'\nBoth API_KEY and NEXT_PUBLIC_APP_LOCALE will be ignored as .env.local has a higher priority, but CLIENT_KEY will become available.