How do I add environment variables to my Vercel project?

The Vercel platform provides the option to define environment variables, allowing you to set encrypted strings for sensitive information, such as API keys and database credentials.

Build Time Variables and Runtime Variables

There are two different environments that your project can be concerned with: build time and runtime. These environments represent the difference between the environment used for building your Project and running your Serverless Functions.

Imagine a scenario where your frontend depends on content from a CMS to build correctly. You might have a script that fetches the data and generates markup accordingly. Authorized access to the CMS most likely depends on tokens that you can supply via environment variables at build time.

In another scenario, you might want to talk to a database via a Serverless Function. Your function will need to securely read the connection details from variables supplied to the runtime environment.

Envrionment Variables UI

The best location to store your variables is through the Environment Variables UI. This is a central location to store environment variables that removes the need for any configuration. If you define an environment variable, it is automatically encrypted and available at both build time and runtime.

You can set variables for Development, Preview, and Production environments separately. Make sure that the variables you are trying to access have been defined for the approporiate stage of development or deployment.

The Environment Variables UI in Project Settings.

Accessing Variables on the Client

Sometimes you might want to expose environment variables on your website directly.

If you are using Next.js, this is all taken care of for you. To access environment variables on the client in Next.js, prefix your variable names with NEXT_PUBLIC_ in the Environment Variables UI and when accessing them on the client also.

You can learn more from the official documentation on the conventions required for accessing the variables successfully.

If you are not using Next.js, this can be done by inlining your build time variables through a custom build plugin such as babel-plugin-transform-inline-environment-variables.


When making environment variables accessible to the client, anyone who inspects your code bundle can determine the values, so make sure not to expose any sensitive information.

Troubleshooting Undefined Environment Variables

  • Ensure that after adding a new environment variable you redeploy your app. Environment variables are made available to the app on each deployment. If you attempt to read an environment variable that was added after the deployment was made, it will be undefined in your app.
  • If you've added the environment variable, but it remains undefined on a new deployment, consider the environment(s) you have added the variable to and make sure the environment variable is present in the UI for the type of deployment you are accessing.
  • During local development, you will need to use the vercel env pull command after adding a new environment variable in the UI and restart your development server with vercel dev - if this is not done, your environment variable will read undefined locally.
  • Printing out the variable's contents is recommended as a troubleshooting step in cases where a function that depends on the variable's value is failing. You can log values directly from your Serverless Function or prefix your build script with echo $MY_ENV_VAR; build command --here.
Updated October 30th 2020