Managing environment variables

Environment variables are key-value pairs configured outside your source code so that each value can change depending on the Environment.

Changes to environment variables are not applied to previous deployments, they only apply to new deployments. You must redeploy your project to update the value of any variables you change in the deployment.

To declare an Environment Variable for your deployment:

1. From your dashboard, select your project. If necessary, you can also set environment variables team-wide so that they will be available for all projects.
2. Select Environment Variables in the sidebar.

3. 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.

   Node.jsGoPythonRuby

   process.env.API_URL;

   os.Getenv("API_URL")

   os.environ.get('API_URL')

   ENV['API_URL']

4. Then, enter the 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.

5. Configure which deployment environment(s) this variable should apply to.

6. Click Save.

7. To ensure that the new Environment Variable is applied to your deployment, you must redeploy your project.

Move variables from the legacy env and build.env properties in vercel.json to your project's Environment Variables settings. Project environment variables are available during both builds and Vercel Function execution.

For example, this legacy configuration defines the same variables for both stages:

{
  "env": {
    "MY_KEY": "this is the value",
    "SECRET": "@my-secret-name"
  },
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}

To migrate these variables:

1. Open your project's Environment Variables settings.
2. Add each variable using the same name as in vercel.json. In this example, add MY_KEY with the value this is the value.
3. For a legacy secret reference such as @my-secret-name, enter the actual secret value as the value of SECRET. Obtain the value from your team's credential store or the service that issued it. The @my-secret-name reference itself isn't the value to migrate.
4. Select the environments where each variable is needed, such as Production, Preview, or Development, and click Save. Use the appropriate value for each environment.
5. Remove the migrated entries from both env and build.env in vercel.json. Remove any objects left empty, while preserving other configuration.
6. Deploy the updated source and configuration. If you deploy through Git, commit and push the configuration change.
7. Verify that the new deployment builds successfully and that the features using these variables work as expected.

When a variable has the same name and value in both legacy properties, add it once per environment. If the values differ between build and runtime, use distinct variable names and update your code before migrating.

Existing deployments keep their previous environment variables. The migrated values apply to new deployments.

To find and view all environment variables.

1. From your dashboard, select your project. You can also view all team-wide environment variables through the Team Settings.
2. Select Environment Variables in the sidebar.
3. Below the Add New form is a list of all the environment variables for the Project.
4. You can search for an existing Environment Variable by name using the search input and/or filter by Environment.
5. To edit or delete the Environment Variable, click the three dots to the right of the Environment Variable name.