How-to
4 min read

Shared Environment Variables

Learn how to use Shared Environment Variables, which are Environment Variables that you define at the Team level and can link to multiple Projects.
Table of Contents

You need Vercel CLI version 28.4.14 or higher to use the features described below.

Shared Environment Variables are Environment Variables that you define at the level of a Vercel Team and can link to multiple Projects.

In the past, when you need to use the same Project Environment Variable in another Project, you will re-create it in that Project. If the value of the Environment Variable changes, you must update the value on both Projects.

Shared Environment Variables help streamline the management of Environment Variables across multiple Projects. These allow you to define an Environment Variable at the Team level and link it to multiple Projects. When a Shared Environment Variable is updated, the change is applied to all linked Projects.

When a Project level Environment Variable and a Shared Environment Variable share the same key and environment, the Project level Environment Variable always overrides the Shared Environment Variable.

Shared Environment Variables are created on the Team Settings page. To create a new Shared Environment Variable, follow these steps:

From the scope selector, select the Team where you would like to create the Environment Variable. Click on the Settings tab and then select Environment Variables from the left navigation.

  1. Key: Fill in the key of the environment variable

  2. Value: Fill in the value of the environment variable

    To add multiple environment variables, you have the following options:

    • Click Add another to add another key-value pair
    • Paste the contents of a .env file inside any key field
    • Import the contents of a .env file by clicking the Import button at the bottom of the form
  3. Environment: Select the Environments where you want to include it

  4. Link to Projects: Select one or more Projects in succession to link the new Shared Environment Variable by using the searchable drop-down. You can keep this empty and link to Projects later as shown in Linking to Projects

  5. Click Save to save your new Shared Environment Variable

The environment(s) chosen for the Shared Environment Variable is used when linked to a Project.

A Shared Environment Variable is activated once it is linked to at least one Project. As shown above, you can link an Environment Variable to a Project during the creation process.

You can link an existing Shared Environment Variable to a Project either at the Project level or the Team level.

For Project-level linking, go to Project SettingsEnvironment Variables.

  1. Click on the Link Shared Environment Variables tab
  2. Select one or more Shared Environment Variables using the search box
  3. Click the Link button

For the Team where the Environment Variables are defined, go to Team SettingsEnvironment Variables.

  1. Scroll down below the Shared Environment Variable creation form

  2. Find the variable you would like to link. You can use the Search box, the Environments drop-down filter and sort by last updated date, name or type to more easily find the variable

  3. Open the context menu for the specific Shared Environment Variable using the vertical ellipsis icon on the right hand side of the row, and click Edit

  4. From the Environment Variable form, you can link additional Projects using the Link to Projects field

  5. Click Save when you are done

There are two ways to remove a Shared Environment Variable from a Project:

  • Unlinking: It is disassociated from the selected Project(s) but continues to exist at the level of the Team
  • Deleting: It is permanently removed from the Team and disconnected from all Projects it was previously linked to

For the Project that you would like to unlink from, go to Project SettingsEnvironment Variables.

  1. Scroll down to the Shared Environment Variables section
  2. Open the context menu for the specific shared environment variable you would like to unlink using the vertical ellipsis icon on the right hand side
  3. Click Unlink from this Project

For the Team where the Environment Variables are defined, go to Team SettingsEnvironment Variables.

  1. Scroll down below the Environment Variable creation form

  2. Find the variable you would like to link. You can use the Search box, the Environments drop-down filter and sort by last updated date, name or type to more easily find the variable

  3. Open the context menu for the specific shared environment variable using the vertical ellipsis icon on the right hand side of the row, and click Edit

  4. From the Environment Variable form, click the minus icon to unlink existing Projects

  5. Click the Save button when you are done

For the Team where the Environment Variables are defined, go to Team SettingsEnvironment Variables.

  1. Scroll down below the Environment Variable creation form
  2. Use the context menu on the specific Shared Environment Variable by clicking the vertical ellipsis icon on the right side of the row
  3. Click the Delete button

This action will remove the Shared Environment Variable from the Vercel Team. It will also unlink the Environment Variable from ALL previously linked Projects.

Last updated on March 28, 2024