Environment Variables are accessible during both the Build Step and Runtime and can be configured for Production, Preview, and Development Environments individually.

This allows you to inject values that you don't want to place directly in your source code and change its behavior depending on the Environment its running in.

To declare an Environment Variable for your deployment, head to the Environment Variables page of your Project Settings.

The Add New section of the Environment Variables page in the Project Settings.

You can add the following types of Environment Variables:

Type
Description
The Environment Variable value is stored as plain text and is visible to any user that has access to the Project. Plaintext Environment Variables should be used for non-sensitive information, such as API_URL.
When selected, you will be prompted to create a new Secret or choose an existing one to populate the value of the Environment Variable. Secrets are encrypted and should be used for sensitive information like passwords or access tokens. Note that if you select Secret, you won't be able to assign the Variable to the Development Environment.
The value is automatically populated by the System when you create a Deployment. References to System Environment Variables can be used to provide your code with information about the System, such as the URL of the Deployment or the name of the Git branch deployed.

Once added, Environment Variables are applied to your subsequent deployments. They can then be consumed during the Build Step by the framework of your choice, or by a Serverless Function at Runtime.

Note: If any Environment Variables values are changed between Deployments, deduplication will always be bypassed. For example, this means that merging to the default branch will no longer result in an instant deployment.

Plaintext Environment Variables

The value of a Plaintext Environment Variable is stored as plain text and is visible to any user that has access to the Project.

To create a new Plaintext Environment Variable, select Plaintext in the first step.

Adding a Plaintext Environment Variable in the Project Settings.

Then, enter the Name of the Environment Variable. For example, if you are using Node.js and you create an Environment Variable named API_URL, it will be available under process.env.API_URL in your code.

Enter the desired Value for your Environment Variable and click Save.

Note that you can copy and paste a multi-line value. Alternatively, you can insert a line break in the Value field by pressing Enter key while holding Shift.

An example of a Plaintext Environment Variable.

Secret Environment Variables

You can populate the value of an Environment Variable with a Secret. They are encrypted and provide a secure way to store and share sensitive information between Deployments.

To create a new Secret Environment Variable, select Secret in the first step.

Enter the desired Name for your Environment Variable.

Adding a Secret Environment Variable in the Project Settings.

In the Value field, you can search and select an existing Secret available in your Personal Account or Team.

Alternatively, you can also create a new Secret. Click on Create new Secret for… to do so.

Creating a new Secret using the Add Secret modal.

Enter the Name and Value of the Secret. When you click Add, the Secret is created.

Lastly, select the desired Environments and click Save.

An example of a Secret Environment Variable.

Note: Secret Environment Variables can't be used with the Development Environment.

Secrets

If you're looking to share a piece of information in Environment Variables across multiple Projects within the same Personal Account or Team on Vercel, Secrets are the best way to accomplish that.

Even if you only want to use the information inside a single Project, Secrets should always be used if you're dealing with sensitive information – like access tokens.

Once created (which can be done through our command-line interface or through the dashboard), they are stored encrypted and their value can only be retrieved again from within a Deployment.

Secrets cannot be renamed. They must be deleted and created with a new name.

In order to delete them, you can use our command-line interface.

System Environment Variables

Vercel provides a set of Environment Variables that are automatically populated by the System, such as the URL of the Deployment or the name of the Git branch deployed.

To expose them to your Deployments, make sure Automatically expose System Environment Variables is checked in your Project Settings.

Automatically exposing System Environment Variables in the Project Settings.

The following System Environment Variables will be exposed to your Deployments:

Name
Description
VERCEL
An indicator that the app is deployed and running on Vercel. Example: 1.
CI
An indicator that the code is running in a Continuous Integration environment. Example: 1. Note: This Variable is only added during Build Step.
VERCEL_ENV
The Environment that the app is deployed an running on. The value can be either production, preview, or development.
VERCEL_URL
The URL of the deployment. Example: my-site-7q03y4pi5.vercel.app.
VERCEL_REGION
The ID of the Region where the app is running. Example: cdg1. Note: This System Environment Variable is only exposed during Runtime for Serverless Functions.
VERCEL_GIT_PROVIDER
The Git Provider the deployment is triggered from. Example: github.
VERCEL_GIT_REPO_SLUG
The origin repository the deployment is triggered from. Example: my-site.
VERCEL_GIT_REPO_OWNER
The account that owns the repository the deployment is triggered from. Example: acme.
VERCEL_GIT_REPO_ID
The ID of the repository the deployment is triggered from. Example: 117716146.
VERCEL_GIT_COMMIT_REF
The git branch of the commit the deployment was triggered by. Example: improve-about-page.
VERCEL_GIT_COMMIT_SHA
The git SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
VERCEL_GIT_COMMIT_MESSAGE
The message attached to the commit the deployment was triggered by. Example: Update about page.
VERCEL_GIT_COMMIT_AUTHOR_LOGIN
The username attached to the author of the commit that the project was deployed by. Example: johndoe.
VERCEL_GIT_COMMIT_AUTHOR_NAME
The name attached to the author of the commit that the project was deployed by. Example: John Doe.
Note: System Environment Variables will be populated with an empty string if the value is not applicable, for example when running development vercel dev during Development or if the Deployment is not triggered by a Git Commit.

References to System Environment Variables

In some cases, you might want to use the value of a System Environment Variable with a custom Environment Variable.

To add an Environment Variable referencing a System value to your Deployment, select Reference to System Environment Variable.

Adding a Reference to a System Environment Variable in the Project Settings.

Enter the desired Name for your Environment Variable.

In the Value field, select the value that you want the System to provide for your Environment Variable when a Deployment is created.

For example, if you enter GIT_SHA and select VERCEL_GIT_COMMIT_SHA, GIT_SHA will be populated with the SHA of the commit that triggered the Deployment.

An example of a Reference to a System Environment Variable.

Environments

For each Environment Variable, you can select one or more Environments to apply the Variable to:

Environment
Description
When selected, the Environment Variable will be applied to your next Production Deployment. To create a Production Deployment, push a commit to the Production Branch or run vercel --prod.
The Environment Variable is applied to your next Preview Deployment. Preview Deployments are created when you push to a branch (for example, my-new-feature) or run vercel.
The Environment Variable is for use when running your project locally, with vercel dev or your preferred development command. To download Development Environment Variables, run vercel env pull.

Development Environment Variables

Note: You need Vercel CLI version 21.0.1 or higher to use the features described in this section.

Environment Variables created for the Development Environment can be downloaded into a local development setup using the vercel env pull command provided by Vercel CLI:

vercel env pull
Downloading Development Environment Variables for project my-lovely-project
✅ Created .env file [510ms]

Downloading Development Environment Variables with the vercel env pull command.

Running the command will create a .env file in your project's directory, which can then be consumed by your framework's Development Command (like next dev).

If you're using vercel dev, there's no need to run vercel env pull, as vercel dev automatically downloads the Development Environment Variables into memory.

Note: Make sure to read this section about whether you should use vercel dev or not.

For more information on the vercel env command, check out this section.

Integration Environment Variables

Integrations can automatically add Environment Variables to your Project Settings. In that case, the Integration Configuration that added it will be displayed:

An Environment Variable added by the Sentry Integration.

Note: Support for Integration Environment Variables was added on April 10th, 2020. Variables added before that date do not have the Integration indication.

Reserved Environment Variables

The following Environment Variable names are reserved and therefore unavailable for use:

  • AWS_REGION
  • AWS_DEFAULT_REGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_KEY
  • AWS_SECRET_ACCESS_KEY
  • AWS_EXECUTION_ENV
  • AWS_LAMBDA_LOG_GROUP_NAME
  • AWS_LAMBDA_LOG_STREAM_NAME
  • AWS_LAMBDA_FUNCTION_NAME
  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE
  • AWS_LAMBDA_FUNCTION_VERSION
  • AWS_SESSION_TOKEN
  • NOW_REGION
  • TZ
  • _HANDLER
  • LAMBDA_TASK_ROOT
  • LAMBDA_RUNTIME_DIR

Deployments that use any of the reserved Environment Variable names will fail during the build step.

Using a .env File

We generally recommend only adding your Environment Variables in the Project Settings, as that's the only way to achieve different Environment Variables based on the Environment (Development, Preview or Production).

Therefore, it's not necessary to use a .env file or configure Environment Variables within the vercel.json file.


Last Edited on August 28th 2020