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 its 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 i -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, Bitbucket, or Origin
• 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.

Use a staging workflow to test changes before serving them on your production domains. Choose a workflow based on what you need to verify:

1. Create a custom environment named staging in your project's Environments settings.
2. Configure Branch Tracking to match your staging branch.
3. Add the environment variables your staging deployment needs. If you import variables from another environment, review the values for your staging services.
4. Assign a domain to the environment, such as staging.example.com.
5. Push to the matching branch to deploy your changes to staging.

The environment's domain points to its latest deployment. You can also deploy from the CLI with vercel deploy --target=staging.

1. Create a Git branch named staging, separate from your production branch.
2. Add a domain such as staging.example.com to your project and assign it to the Git branch. In the domain settings, select Preview and set Git Branch to staging.
3. Add Preview environment variables for that branch. Branch-specific values override Preview variables with the same name, so you only need to add the values that differ.
4. Push to staging to create a preview deployment. After changing environment variables, create a new deployment to apply them.
5. When testing is complete, merge your changes into the production branch. Keep the staging branch for future testing.

Confirm that the staging domain is assigned to Preview and the intended branch. New projects create a production deployment first, even when deployed from another branch.

For a final check with production environment variables, stage a production deployment. In your project's Environments settings, select Production, open Branch Tracking, and disable Auto-assign Custom Production Domains.

Deployments from your production branch then wait for manual promotion before serving traffic on your production domains. Verify the deployment through its generated URL, then promote it to production. Promotion assigns the production domains without rebuilding.

Staged production deployments use production environment variables, so testing can access production services and data. Use a custom environment or preview branch with staging credentials when you need separate resources.

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.

The first deployment of a new project is always a production deployment. This happens even when you:

• Import a Git repository in the dashboard
• Run vercel or vercel deploy from the CLI without --prod
• Deploy from a branch that is not your production branch

Vercel does this so every new project has a production deployment and can receive production domains right away.

After that first production deployment, later deployments follow the usual rules:

• Commits to the production branch, or vercel --prod, create production deployments
• Other branches, pull requests, and vercel without --prod create preview deployments

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.

curl --request POST \
  --url https://api.vercel.com/v9/projects/<project-id-or-name>/custom-environments \
  --header "Authorization: Bearer $VERCEL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "slug": "<environment_name_slug>",
    "description": "<environment_description>",
  }'

import { Vercel } from '@vercel/sdk';
 
const vercel = new Vercel({
  bearerToken: '<YOUR_BEARER_TOKEN_HERE>',
});
 
async function run() {
  const result = await vercel.environment.createCustomEnvironment({
    idOrName: '<project-id-or-name>',
    requestBody: {
      slug: '<environment_name_slug>',
      description: '<environment_description>',
    },
  });
  // Handle the result
  console.log(result);
}
 
run();

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

You can scope Vercel Connect token access and trigger forwarding to a Custom Environment. This lets a staging or QA deployment use a connector without enabling it in any built-in Connect environment: Production, Preview, or Development.

In the Vercel Dashboard, open a connector's Projects section and select the Custom Environment when adding or editing a project link. From the CLI, pass the environment's slug:

vercel connect attach slack/acme-slack --environment staging

You can also select the Custom Environment as a trigger destination in the dashboard or with the CLI:

vercel connect attach slack/acme-slack --environment staging --triggers \
  --trigger-environment staging --trigger-path /api/slack-events

The trigger target is added to the connector's project link automatically. For a project with no existing trigger destinations, passing --environment staging, as shown above, keeps token access limited to staging. Existing trigger destinations remain registered, and the CLI preserves any Custom Environments they require on the project link. Before sending events to a Custom Environment, deploy to it and assign a domain to the environment. The domain must be verified and serve the environment's latest deployment directly rather than redirect elsewhere.

See Project links for token-access configuration and Triggers for destination setup and lifecycle behavior.

Each plan includes a number of custom environments per project at no additional cost. You can purchase more for any project in packs of five environments:

To purchase additional custom environments:

1. Go to your project's Environments settings in the Vercel Dashboard
2. In the Custom Environments section, use the stepper to set the number of environments for the project
3. Click Save, then confirm the updated monthly cost

To stop the monthly charge, reduce the number back to your plan's included amount in the same section. If the project uses more environments than the reduced amount allows, delete custom environments first: reductions below current usage are not accepted.

Purchased packs apply to a single project. Members with permission to update the team's billing plan can change pack quantities.

• Learn about the different environments on Vercel