Environment Variables are key-value pairs configured outside your source code so that each value can change depending on the Environment.
Your source code can read these values to change behavior during the Build Step or during Serverless Function execution.
All values are encrypted at rest and visible to any user that has access to the Project. It is safe to use both non-sensitive and sensitive data, such as tokens.
Changes to Environment Variables are not applied to previous deployments, they only apply to new deployments.
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.
Enter the desired Name for your 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.
process.env.API_URL;
Accessing environment variables with supported runtime languages
Then, enter the desired Value for your Environment Variable. The value is encrypted at rest so it is safe to add sensitive data like authentication tokens or private keys.
You can then configure which Environments this variable should apply to.
Finally, click Save.
Just below the Add New form is a list of all the Environment Variables for the Project.
You can search for an existing Environment Variable by name using the search input and/or filter by Environment and Git Branch (in the case of the Preview Environment).
Clicking the three dots to the right allows you to edit or delete the Environment Variable.
An example of an Environment Variable with the search and filter inputs above.
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 that is not the Production Branch or run vercel . | |
The Environment Variable is used when running your project locally with vercel dev or your preferred development command. To download Development Environment Variables, run vercel env pull . |
Preview Environment Variables are applied to deployments from any Git branch that does not match the Production Branch. When you add a Preview Environment Variable, you can choose to apply to all Preview branches or you can select a specific branch.
When you push to a branch, a combination of Preview Environment Variables and branch-specific variables (if any) will be used. Any branch-specific variables will override other variables with the same name. This means you don't need to replicate all your existing Preview Environment Variables for each branch – you only need to add the values you wish to override.
Adding an Environment Variable to the staging
branch.
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 the current 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.
vercel dev
or not.For more information on the vercel env
command, check out this section.
Integrations can automatically add Environment Variables to your Project Settings. In that case, the Integration that added the Variable will be displayed:
An Environment Variable added by the Sentry Integration.
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
LAMBDA_TASK_ROOT
LAMBDA_RUNTIME_DIR
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 exposed 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 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 . |
Frameworks typically use a prefix in order to expose Environment Variables to the browser.
The following prefixed Environment Variables will be available during the Build Step, based on the Project's selected Framework Preset.
Name | Description |
---|---|
NEXT_PUBLIC_VERCEL_ENV | The Environment that the app is deployed an running on. The value can be either production , preview , or development . |
NEXT_PUBLIC_VERCEL_URL | The URL of the deployment. Example: my-site-7q03y4pi5.vercel.app |
NEXT_PUBLIC_VERCEL_GIT_PROVIDER | The Git Provider the deployment is triggered from. Example: github . |
NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG | The origin repository the deployment is triggered from. Example: my-site . |
NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER | The account that owns the repository the deployment is triggered from. Example: acme . |
NEXT_PUBLIC_VERCEL_GIT_REPO_ID | The ID of the repository the deployment is triggered from. Example: 117716146 . |
NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF | The git branch of the commit the deployment was triggered by. Example: improve-about-page . |
NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA | The git SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081 . |
NEXT_PUBLIC_VERCEL_GIT_COMMIT_MESSAGE | The message attached to the commit the deployment was triggered by. Example: Update about page . |
NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_LOGIN | The username attached to the author of the commit that the project was deployed by. Example: johndoe . |
NEXT_PUBLIC_VERCEL_GIT_COMMIT_AUTHOR_NAME | The name attached to the author of the commit that the project was deployed by. Example: John Doe . |
vercel dev
during Development or if the Deployment is not triggered by a Git Commit.