Closes https://github.com/vercel/next.js/issues/14570 Closes https://github.com/vercel/next.js/issues/14576 - The example features everything on the page in our docs while still being quite simple - Added a link to it in the documentation - Deprecated the with-now-env example
3.8 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, upgrade or refer to Environment Variables in next.config.js.
Examples
Next.js comes with built-in support for environment variables, which allows you to do the following:
Loading Environment Variables
Next.js has built-in support for loading environment variables from .env.local
into process.env
.
An example .env.local
:
DB_HOST=localhost
DB_USER=myuser
DB_PASS=mypassword
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 Next.js data fetching methods and API routes.
For example, using getStaticProps
:
// 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,
})
// ...
}
Exposing Environment Variables to the Browser
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.
In order to expose a variable to the browser you have to prefix the variable with NEXT_PUBLIC_
. For example:
NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk
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.
// pages/index.js
import setupAnalyticsService from '../lib/my-analytics-service'
// NEXT_PUBLIC_ANALYTICS_ID can be used here as it's prefixed by NEXT_PUBLIC_
setupAnalyticsService(process.env.NEXT_PUBLIC_ANALYTICS_ID)
function HomePage() {
return <h1>Hello World</h1>
}
export default HomePage
Default Environment Variables
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.
Next.js allows you to set defaults in .env
(all environments), .env.development
(development environment), and .env.production
(production environment).
.env.local
always overrides the defaults set.
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.
Environment Variables on Vercel
When deploying on Vercel you can configure secrets in the Environment Variables section of the project in the Vercel dashboard.
You can still use .env
, .env.development
and .env.production
to add defaults.
If you've configured Development Environment Variables you can pull them into a .env.local
for usage on your local machine using the following command:
vercel env pull .env.local