Skip to Content

Local Development Environment

Vercel provides three default environments (Local, Preview, and Production):


Environments

Install the Vercel CLI:


Deployments

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.


Environments

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.

Preview Environment (Pre-production)

  1. Link your Vercel project with your local directory:vercel link
  2. Pull environment variables locally for use with application development:

    vercel envpull

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

first deployment of a new project is always a production deployment. The preview rules above apply only after that first production deployment exists.

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.

Setting up a staging environment

Using a custom environment for staging

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


Use it when

You need a named environment with its own branch tracking, domain, and variables.

Availability

Pro and Enterprise

You want a persistent staging branch with a domain and branch-specific variables.

You want to verify a build with production configuration before assigning production domains.

All plans, including Hobby

All plans

  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.

Using a preview branch for 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.

Verifying a production build before promotion

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.

Production Environment

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.

First deployment

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 environmentsare availableon Enterprise and Pro plans

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

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


Creating a custom environment Custom Environments

cURL

  1. Go to your project's Environments settings in the Vercel Dashboard
  2. 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

SDK

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 envaddMY_KEYstaging


Using custom environments with Vercel Connect

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 connectattachslack/acme-slack--environmentstaging

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

vercel connectattachslack/acme-slack--environmentstaging--triggers \

--trigger-environmentstaging--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.

Using custom environments with Marketplace resources

Pricing and limits

See setup and verification steps and Deployment Action environment targets.


Plan

Included per project

Additional environments

You can connect a Native Marketplace resource to a Custom Environment. In Project Settings, environment variables provided by the resource, such as a database's DATABASE_URL, apply to the environments selected on the resource connection.

Maximum per project

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:

Pro

To purchase additional custom environments:

Enterprise

$50 per month for each pack of five

$50 per month for each pack of five

22

Deployments

Last updated September 17, 2026

Cross-link map: Environments (/docs/deployments/environments)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesHow to set up a staging environment on Vercel — Set up a staging environment on Vercel with custom environments, staged production deployments, or a branch-based previeEnvironment variables — Learn more about environment variables on Vercel.Managing environment variables across environments — Add, sync, and verify environment variables across development, preview, production, and custom environments using the CCreate a custom environment for the current project. — POST /v9/projects/{idOrName}/custom-environments — Creates a custom environment for the current project. Cannot be namedDeploying Git Repositories with Vercel — Vercel automatically deploys supported Git repositories on every branch push and when changes merge into the productionThis page links to (15)Vercel CLI Overview — Learn how to use the Vercel command-line interface \(CLI\) to manage and configure your Vercel Projects from the commandVercel Connect — Give your agents and services secure, short-lived access to third-party APIs like Slack, GitHub, Microsoft, and SnowflakProject links — A project link binds a connector to a Vercel project, scoped to one or more environments. The link is what authorizes aTriggers — Incoming webhooks from third-party services, verified by Vercel Connect and forwarded to your projects.Accessing Deployments through Generated URLs — When you create a new deployment, Vercel will automatically generate a unique URL which you can use to access that partiPromoting Deployments — Learn how to promote deployments to production on Vercel.Assigning a custom domain to an environment — Learn how to add a custom domain to your Vercel project, verify it, and correctly set the DNS or Nameserver values.Assigning a domain to a Git branch — Learn how to assign a domain to a different Git branch with this guide.Deploying & Redirecting Domains — Learn how to deploy your domains and set up domain redirects with this guide.Environment variables — Learn more about environment variables on Vercel.Frameworks on Vercel — Vercel supports a wide range of the most popular frameworks, optimizing how your application builds and runs no matter wDeploying Git Repositories with Vercel — Vercel automatically deploys supported Git repositories on every branch push and when changes merge into the productionDeployment integration actions — These actions allow integration providers to set up automated tasks with Vercel deployments.Storage on Vercel Marketplace — Connect Postgres, Redis, NoSQL, and other storage solutions through the Vercel Marketplace. Run SQL queries, edit data,Vercel REST API Reference — Interact programmatically with your Vercel account using the SDK or direct HTTP requests.Pages that link here (121)By site: vercel-changelog (6) · vercel-kb (36) · vercel-web (2) · vercel-docs (77)From vercel-changelogAdditional custom environments can now be purchasedNative Marketplace integrations now support custom environmentsPrioritize production builds available on all plansSet team-wide defaults for Deployment ProtectionVercel Connect now supports Custom EnvironmentsVercel Secure Compute now supports multiple environmentsFrom vercel-kbAre Vercel Preview Deployments indexed by search engines? — Vercel Preview Deployments aren't indexed by default. Learn how the noindex header works, how to confirm it, and the cusHow to prepare your storefront for Black Friday traffic — A practical checklist for keeping your storefront fast and your checkout path healthy through Black Friday and Cyber MonCan I get a fixed IP address for my Vercel deployments? — Vercel deployments use dynamic IPs by default. Learn how Static IPs, Secure Compute, and AWS PrivateLink give you a fixeHow to use a non-default branch for production deployments on Vercel — Learn how to set a non-default branch for production on Vercel. Open the Production environment, change branch tracking,How to Deploy a TanStack Start app to Vercel — Deploy a TanStack Start app to Vercel with the Nitro Vite plugin. Covers Git and CLI deployment, Fluid compute defaults,Deploy a Node.js Fastify app on Vercel with Docker — Build a Node.js application with Fastify and Docker, then deploy it to Vercel Functions. Learn how to configure environmDeploy PHP on Vercel with Docker — Build a PHP application with FrankenPHP and Docker, then deploy it to Vercel Functions with managed configuration, storaDeploy Rust on Vercel with Docker — Build a Rust application with Axum and Docker, then deploy it to Vercel Functions. Learn how to configure environment vaDeploy ASP.NET Core on Vercel with Docker — Build a .NET application with Docker and deploy it to Vercel Functions. Learn how to configure environment variables, inConditional Build Commands: Environment, Branch, and Custom Workflows — Run a different Vercel build command for each environment or Git branch using a shell script, vercel.json, or vercel.ts,Full-stack previews on Vercel — Learn how to use full-stack previews for your Vercel projects. Deploy Next.js, FastAPI, and a containerized Go service tDeploy to Vercel with Self-Hosted Git Pipelines \(GitLab & Bitbucket\) — Learn how to use GitLab Pipelines to deploy to Vercel including support for self-managed GitLab.How to add and manage environment variables on Vercel — Add environment variables to Vercel through the dashboard, CLI, or REST API, scope them to each environment, and pull thHow to use Vercel Flags across projects — Evaluate flags across projects using a source project SDK Key in the consumer project via a custom adapterHow Vercel Flags resolves environments — Configure Vercel Flags per environment by using environment-scoped SDK Keys that map your Vercel deployment environmentMigrate to Vercel from Cloudflare — Migrate your website's configuration from Cloudflare Pages or Workers to VercelMigrate to Vercel from Netlify — Migrate your website's configuration from Netlify to VercelHow to choose a Salesforce Commerce Cloud storefront: PWA Kit, Storefront Next, or Next.js — Compare PWA Kit, Storefront Next, and a Next.js storefront on Vercel for Salesforce Commerce Cloud. Learn how caching, pHow to set up a staging environment on Vercel — Set up a staging environment on Vercel with custom environments, staged production deployments, or a branch-based previeHow to ship an Elysia app on Vercel — Deploy a Elysia app to Vercel with zero configuration. Learn how to ship from a template, the Vercel CLI, or Git, and coHow to ship an Express app on Vercel — Deploy an Express app to Vercel with zero configuration. Configure response streaming, middleware, cron jobs, the Bun ruHow to ship a Fastify app on Vercel — Deploy a Fastify app to Vercel with zero configuration, then add streaming, lifecycle hooks, cron jobs, and observabilitHow to ship an H3 app on Vercel — Deploy an H3 app to Vercel with zero configuration. Learn to configure streaming, middleware, cron jobs, the Bun runtimeHow to ship a Hono app on Vercel — Deploy a Hono app to Vercel with zero configuration. Learn how to ship from a template, the Vercel CLI, or Git, and confHow to ship a Koa app on Vercel — Deploy a Koa app to Vercel with zero configuration. Learn how to ship from the Vercel CLI or Git, and configure responseHow to ship a NestJS app on Vercel — Deploy a NestJS app to Vercel with zero configuration. Learn how to ship from a template, the Nest CLI, or Git, and confHow to ship a Nitro app on Vercel — Deploy a Nitro app to Vercel with zero configuration. Learn how to ship from a template, the Vercel CLI, or Git, and conGive your software factory a browser — Add a KERNEL cloud browser to the eve software factory template so Foreman can reproduce flow bugs, sign in through manaUsing Vercel as a Standalone CDN — Use Vercel's external rewrites to proxy and cache content from external websites or APIs through Vercel's global edge neThe Complete Guide to Vercel Connect — Use Vercel Connect to call provider APIs like Slack, GitHub, Linear, Microsoft, Discord, Snowflake, and Salesforce fromVercel vs Akamai — A detailed guide to Vercel vs Akamai: compute models, AI infrastructure, framework support, media streaming, CDN capabilVercel vs Fastly — A detailed guide to Vercel vs Fastly: full-stack application platform vs edge infrastructure layer, covering framework sVercel vs Netlify — A detailed guide to Vercel vs Netlify: runtimes, compute architecture, AI infrastructure, security, and when to choose eVercel vs Northflank — A detailed guide to Vercel vs Northflank: Fluid compute, CDN and caching, container image functions, security defaults,Vercel vs Railway — A detailed guide to Vercel vs Railway: serverless vs always-on containers, container images via Dockerfile.vercel, frameVercel vs Render — A detailed guide to Vercel vs Render: compute models, AI infrastructure, Docker and container image support, backgroundFrom vercel-webLife of a Vercel request: Application-aware routingThe developer experience of the Frontend CloudFrom vercel-docsManaging Builds — Vercel allows you to increase the speed of your builds when needed in specific situations and workflows.Data Cache for Next.js — Vercel Data Cache is a specialized cache that stores responses from data fetches in Next.js App RouterVercel CDN overview — Vercel's CDN is a globally distributed platform that handles routing, caching, security, and compression for every deplovercel build — Learn how to build a Vercel Project locally or in your own CI environment using the vercel build CLI command.vercel deploy — Learn how to deploy your Vercel projects using the vercel deploy CLI command.Deploying Projects from Vercel CLI — Learn how to deploy your Vercel Projects from Vercel CLI using the vercel or vercel deploy commands.vercel list — Learn how to list out all recent deployments for the current Vercel Project using the vercel list CLI command.vercel pull — Learn how to update your local project with remote environment variables using the vercel pull CLI command.vercel redeploy — Learn how to redeploy your project using the vercel redeploy CLI command.vercel target — Work with custom environments using the --target flag in Vercel CLI.Comments Overview — Comments allow teams and invited participants to give direct feedback on preview deployments. Learn more about CommentsProject links — A project link binds a connector to a Vercel project, scoped to one or more environments. The link is what authorizes aTriggers — Incoming webhooks from third-party services, verified by Vercel Connect and forwarded to your projects.Quickstart — Create your first connector in Vercel Connect, install the SDK, and request a runtime provider token from your code.Getting started with cron jobs — Learn how to schedule cron jobs to run at specific times or intervals.Restrict access to deployments with Vercel Authentication — Vercel Authentication restricts access to your deployments so only authorized users can view and comment on your site.Deployment Retention — Learn how Deployment Retention policies affect a deployment's lifecycleDeploying to Vercel — Create, verify, and manage preview and production deployments on Vercel from Git, Vercel CLI, or the REST API.Deployment Policies — Use a deployment policy to control which Git sources and deployment mechanisms can deploy to your team and projects, perAccessing Deployments through Generated URLs — When you create a new deployment, Vercel will automatically generate a unique URL which you can use to access that partiPreview Deployment Suffix — When you create a new deployment, Vercel will automatically generate a unique URL which you can use to access that partiTroubleshooting Build Errors — Learn how to resolve common scenarios you may encounter during the Build step, including build errors that cancel a deplAssigning a custom domain to an environment — Learn how to add a custom domain to your Vercel project, verify it, and correctly set the DNS or Nameserver values.Assigning a domain to a Git branch — Learn how to assign a domain to a different Git branch with this guide.Deploying & Redirecting Domains — Learn how to deploy your domains and set up domain redirects with this guide.Deploying with Vercel Drop — Vercel Drop lets you deploy a file or folder by dragging it into your browser, with no Git or CLI required.Environment variables — Learn more about environment variables on Vercel.Managing environment variables — Learn how to create and manage environment variables for Vercel.Rotating environment variables — Safely rotate API keys, tokens, and other secrets in your Vercel environment variables.Sensitive environment variables — Environment variables that cannot be decrypted once created.Feature Flag Configuration — Learn how to configure individual feature flags in the Vercel Dashboard.Frameworks on Vercel — Vercel supports a wide range of the most popular frameworks, optimizing how your application builds and runs no matter wBackends on Vercel — Vercel supports a wide range of the most popular backend frameworks, optimizing how your application builds and runs noElysia on Vercel — Build fast TypeScript backends with Elysia and deploy to Vercel. Learn the project structure, plugins, middleware, and hExpress on Vercel — Deploy Express applications to Vercel with zero configuration. Learn about middleware and Vercel Functions.Fastify on Vercel — Deploy Fastify applications to Vercel with zero configuration.Hono on Vercel — Deploy Hono applications to Vercel with zero configuration. Learn about observability, ISR, and custom build configuratiKoa on Vercel — Deploy Koa applications to Vercel with zero configuration.NestJS on Vercel — Deploy NestJS applications to Vercel with zero configuration.Nitro on Vercel — Deploy Nitro applications to Vercel with zero configuration. Learn about observability, ISR, and custom build configuratCreate React App on Vercel — Deploy Create React App projects to Vercel and add Preview Deployments, Web Analytics, Speed Insights, and ObservabilityNext.js on Vercel — Vercel is the native Next.js platform, designed to enhance the Next.js experience.SvelteKit on Vercel — Deploy SvelteKit applications to Vercel and configure the adapter, rendering, streaming, ISR, analytics, and Routing MidRuntimes — Runtimes transform your source code into Functions, which are served by our CDN. Learn about the official runtimes suppoDeploying Git Repositories with Vercel — Vercel automatically deploys supported Git repositories on every branch push and when changes merge into the productionDeploying Bitbucket Projects with Vercel — ​Vercel for Bitbucket automatically deploys your Bitbucket projects with Vercel, providing Preview Deployment URLs, andDeploying GitHub Projects with Vercel — Vercel for GitHub automatically deploys your GitHub projects with Vercel, providing Preview Deployment URLs, and automatDeploying GitLab Projects with Vercel — ​Vercel for GitLab automatically deploys your GitLab projects with Vercel, providing Preview Deployment URLs, and automaResponse headers — Learn about the response headers sent to each Vercel deployment and how to use them to process responses before sendingPerforming an Instant Rollback on a Deployment — Learn how to perform an Instant Rollback on your production deployments and quickly roll back to a previously deployed pUsing Vercel with Microsoft Azure — Run your frontend on Vercel alongside backends hosted in Microsoft Azure, with private network connectivity, keyless autIntegrating Vercel and Kubernetes — Deploy your frontend on Vercel alongside your existing Kubernetes infrastructure.Runtime Logs — Learn how to search, inspect, and share your runtime logs with the Logs tab.Manage and optimize usage for Observability — Learn how to understand the different charts in the Vercel dashboard, how usage relates to billing, and how to optimizeManaging microfrontends — Learn how to manage your microfrontends on Vercel.Getting started with microfrontends — Learn how to get started with microfrontends on Vercel.Microfrontends Routing — Configure which microfrontend handles each path and understand how Vercel selects deployments.Static IPs — Access IP-restricted backend services through shared static egress IPs for Pro and Enterprise teams.Connect to your own API — Learn how to configure your own API to trust Vercel's OpenID Connect \(OIDC\) Identity Provider \(IdP\)Account Plans on Vercel — Learn about the different plans available on Vercel.Multi-Project Platforms Quickstart — Programmatically host code for user-generated or AI-generated applications on Vercel.Legacy Metrics — Learn about legacy usage metrics, including Bandwidth, Requests, Vercel Function Invocations, and Vercel Function ExecutStatic Configuration with vercel.json — Learn how to use vercel.json to configure and override the default behavior of Vercel from within your project.Programmatic Configuration with vercel.ts — Define your Vercel configuration in vercel.ts with @vercel/config for type-safe routing and build settings.Projects overview — A project is where you deploy and operate frontend apps, APIs, backends, containers, and agent workloads on Vercel.Deploying a project from the CLI — Set up and deploy a Vercel project using the CLI, from linking to production.Monitoring Reference — This reference covers the clauses, fields, and variables used to create a Monitoring query.Query Reference — Use this reference to find the event types, metrics, aggregations, dimensions, and operators available in Query.Access Roles — Learn about the different roles available for team members on a Vercel account.Redirects — Learn how to use redirects on Vercel to instruct Vercel's platform to redirect incoming requests to a new URL.SAML Single Sign-On — Learn how to configure SAML SSO for your organization on Vercel.Speed Insights Overview — This page lists out and explains all the performance metrics provided by Vercel's Speed Insights feature.Vercel Toolbar — Learn how to use the Vercel Toolbar to leave feedback, navigate through important dashboard pages, share deployments, usAdd the Vercel Toolbar to local and production environments — Learn how to use the Vercel Toolbar in production and local environments.Interaction Timing Tool — The interaction timing tool allows you to inspect in detail each interaction's latency and get notified for interactionsLayout Shift Tool — The layout shift tool gives you insight into any elements that may cause layout shifts on the page.Managing the visibility of the Vercel Toolbar — Learn how to enable or disable the Vercel Toolbar for your team, project, and session.

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.

Generated URLs

  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

Previous

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