---
title: Per-environment and per-branch Build Commands on Vercel
description: Customize your commands for specific behaviors based on branch, environment, and more.
url: /kb/guide/per-environment-and-per-branch-build-commands
canonical_url: "https://vercel.com/kb/guide/per-environment-and-per-branch-build-commands"
published: 2025-11-03
last_updated: 2025-11-10
authors: Anthony Shew
related:
  - /docs/projects/environment-variables/system-environment-variables
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Dynamically run build commands](https://vercel.com/kb/guide/dynamic-build-commands?from=related) — Learn how to run different scripts based on the environment or branch.
- [vercel build](https://vercel.com/docs/cli/build?from=related) — Learn how to build a Vercel Project locally or in your own CI environment using the vercel build CLI command.
- [Build Features](https://vercel.com/docs/builds/build-features?from=related) — Learn how to customize your deployments using Vercel's build features.
- [Manage Across Environments](https://vercel.com/docs/environment-variables/manage-across-environments?from=related) — Add, sync, and verify environment variables across development, preview, production, and custom environments using the C
- [Project Linking](https://vercel.com/docs/cli/project-linking?from=related) — Learn how to link existing Vercel Projects with Vercel CLI.
- [Git Integrations](https://vercel.com/docs/git?from=related) — Vercel allows for automatic deployments on every branch push and merges onto the production branch of your GitHub, GitLa
- [How can I add a custom build step to my project? ](https://vercel.com/kb/guide/how-can-i-add-a-custom-build-step-to-my-project?from=related) — Learn how to add a custom build step for your project.
- [How do I use the "Ignored Build Step" field on Vercel?](https://vercel.com/kb/guide/how-do-i-use-the-ignored-build-step-field-on-vercel?from=related) — Instructions on how to use the "Ignored Build Step" field to programmatically prevent a new deployment from being built.
- [How do I set up a staging environment on Vercel?](https://vercel.com/kb/guide/set-up-a-staging-environment-on-vercel?from=related) — Information on how to set up a staging environment on Vercel.
- [How can I use GitLab Pipelines with Vercel?](https://vercel.com/kb/guide/how-can-i-use-gitlab-pipelines-with-vercel?from=related) — Learn how to use GitLab Pipelines to deploy to Vercel including support for self-managed GitLab.

Full cross-link map for this page: [/kb/guide/per-environment-and-per-branch-build-commands.graph.md](/kb/guide/per-environment-and-per-branch-build-commands.graph.md)
<!-- /docsgraph:related -->


For certain workflows, it may be useful to execute different scripts based on specific environments or branch names. To do this, you'll create a `vercel.sh` file in your repository that your Build Command uses to run conditional logic.

## 1\. Set up your scripts in `package.json`

First, you'll need the scripts that you want to run. For example, here is are a couple scripts that are meant to run in different environments:

```json
{
  "scripts": {
    "build:production": "next build",
    "build:preview": "echo \"Let's build a preview!\" && next build"
  }
}
```

## 2\. Create a `vercel.sh` file

Make a `vercel.sh` file in your project's root directory. We'll write some conditional logic here to run different scripts in different environments:

```bash
#!/bin/bash
 
if [[ $VERCEL_ENV == "production"  ]] ; then 
  npm run build:production
else 
  npm run build:preview
fi
```

This file is written using Bash but you can also use Node.js. Additionally, this file can be adjusted for other [System Environment Variables on Vercel](https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables) like branch names.

## 3\. Set your Build Command to use the new file

Last, set the project to use the the new file as its entrypoint for the Build Command. You can do this two ways:

### Using a vercel.json file

```json
{
  "buildCommand": "sh vercel.sh"
}
```

### Using the project dashboard