Environments

Vercel provides three default environments—Local, Preview, and Production:

1. Local Development: developing and testing code changes on your local machine
2. Preview: deploying for further testing, QA, or collaboration without impacting your live site
3. Production: deploying the final changes to your user-facing site with the production domain

Pro and Enterprise teams can create Custom Environments for more specialized workflows (e.g., staging, QA). Every environment can define it’s own unique environment variables, like database connection information or API keys.

This environment is where you develop new features and fix bugs on your local machine. When building with frameworks, use the Vercel CLI to pull the environment variables for your project.

1. Install the Vercel CLI:

   npm install -g vercel

2. Link your Vercel project with your local directory:

   vercel link

3. Pull environment variables locally for use with application development:

   vercel env pull

This will populate the .env.local file in your application directory.

Preview environments allow you to deploy and test changes in a live setting, without affecting your production site. By default, Vercel creates a preview deployment when you:

• Push a commit to a branch that is not your production branch (commonly main)
• Create a pull request (PR) on GitHub, GitLab, or Bitbucket
• Deploy using the CLI without the -prod flag, for example just vercel

Each deployment gets an automatically generated URL, and you'll typically see links appear in your Git provider’s PR comments or in the Vercel Dashboard.

There are two types of preview URLs:

• Branch-specific URL – Always points to the latest changes on that branch
• Commit-specific URL – Points to the exact deployment of that commit

Learn more about generated URLs.

The Production environment is the live, user-facing version of your site or application.

By default, pushing or merging changes into your production branch (commonly main) triggers a production deployment. You can also explicitly deploy to production via the CLI:

vercel --prod

When a production deployment succeeds, Vercel updates your production domains to point to the new deployment, ensuring your users see the latest changes immediately. For advanced workflows, you can disable the auto-promotion of deployments and manually control promotion.

Custom environments are useful for longer-running pre-production environments like staging, QA, or any other specialized workflow you require.

Team owners and project admins can create, update, or remove custom environments.

1. Go to your Project Settings in the Vercel Dashboard
2. Under Environments, click Create Environment
3. Provide a name (e.g., staging), and optionally:
   • Branch Tracking to automatically deploy whenever a matching branch is pushed
   • Attach a Domain to give a persistent URL to your environment
   • Import variables from another environment to seed this environment with existing environment variables

You can deploy, pull, and manage environment variables to your custom environment with the CLI:

# Deploy to a custom environment named "staging":
vercel deploy --target=staging
 
# Pull environment variables from "staging":
vercel pull --environment=staging
 
# Add environment variables to "staging":
vercel env add MY_KEY staging

Custom environments are available at no additional cost on the Pro and Enterprise plans. The number of custom environments you can create is based on your plan:

• Pro: 1 custom environment per project
• Enterprise: 12 custom environments per project