Deployment Environments

A typical deployment lifecycle for web development has the following steps:

• A local preview on the developer's computer
• A preview of the changes on a remote test server
• Your changes in production on a remote production server

Environments provide a solution for this deployment lifecycle on Vercel. The production environment is usually connected to your production domain and is only deployed under certain conditions. The preview environment is similar to the staging environment so that you can test your code remotely and preview changes without affecting the production instance.

You can define environment variables for each environment directly from the Project settings. These variables are available during the build process and can be used to configure your application based on the environment.

Sometimes called "local" or "development", this environment is where you develop and test your application locally on your computer.

To learn more, see Local Development Environments.

A preview environment is a pre-defined environment that is automatically created for all Vercel users when you make a commit to a branch that is not the production branch (for example, main) or deploy your app by using vercel (no --prod flag).

When you push changes, you'll get an automatically-generated URL that contains your latest changes.

You can set specific environment variables for the preview deployment from your project's Settings page.

To learn more about preview deployments, see Preview Deployments.

Custom environments allow Pro and Enterprise teams to define pre-production environments, such as staging or QA, from the Vercel dashboard. This functionality allows you to reshape your release workflow by separating it from code management.

You can configure these environments with branch rules that automatically deploy your branch when the branch name matches the rule. You can also attach a domain to your environment, set environment variables, or import environment variables from another environment.

To learn more, see Custom Environments.

Production deployments are usually made when you do either of the following:

• When you merge or push to the production branch (commonly main)
• When you make a deployment using the vercel --prod command

By default, when you trigger a production deployment, Vercel automatically updates the production domain(s) with the latest deployment of your application.

To learn more about production environments, see Production Environment.

Environment Variables are key-value pairs, that are configured outside your source code, and can change depending on the environment. Vercel encrypts all environment variables and only decrypts them at build or runtime. They're also subject to RBAC and so only certain team members can make changes to them. Environment variables are therefore ideal to use for authentication tokens, API keys, and connection strings.

These variables are available during the build process and can be used to configure your application based on the environment.

You can configure different Environment Variables for Production, Pre-production, and local environments directly from the Project settings in the Vercel Dashboard. For more information on managing Environment Variables, see Managing Environment Variables.

If you change the value of an environment variable for a deployed project, you must redeploy your project to update the value of these variables in the deployment.

The vercel env CLI command provides many options to work with your project's environment variables. For example:

• To add: vercel env add
• To remove: vercel env remove
• To pull the latest: vercel env pull

To learn more, see the CLI documentation.

Some frameworks do not use package.json to select a specific version to install during build time. In this case, you can use an Environment Variable to define your framework's version in the following cases:

For example, to select Hugo v0.92.2, you will add an Environment Variable named HUGO_VERSION with the value 0.92.2.

The value must match an existing GitHub Release with an attached asset. For example, Hugo 0.92.2 exists but Hugo 0.92 does not exist.