---
title: Dynamically run build commands
description: Learn how to run different scripts based on the environment or branch.
url: /kb/guide/dynamic-build-commands
canonical_url: "https://vercel.com/kb/guide/dynamic-build-commands"
published: 2025-11-03
last_updated: 2026-07-16
authors: DX Team
related:
  - /docs/deployments/configure-a-build
  - /docs/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.

- [Per-environment and per-branch Build Commands on Vercel](https://vercel.com/kb/guide/per-environment-and-per-branch-build-commands?from=related) — Customize your commands for specific behaviors based on branch, environment, and more.
- [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 System](https://vercel.com/docs/fundamentals/builds?from=related) — Learn how Vercel transforms your source code into optimized assets ready to serve globally.
- [Builds](https://vercel.com/docs/builds?from=related) — Understand how the build step works when creating a Vercel Deployment.
- [Deploy from CLI](https://vercel.com/docs/projects/deploy-from-cli?from=related) — Set up and deploy a Vercel project using the CLI, from linking to production.
- [Managing Builds](https://vercel.com/docs/builds/managing-builds?from=related) — Vercel allows you to increase the speed of your builds when needed in specific situations and workflows.
- [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 can I use the Vercel CLI for custom workflows?](https://vercel.com/kb/guide/using-vercel-cli-for-custom-workflows?from=related) — You can use the Vercel CLI to deploy any application, including custom git providers and restricted source code.
- [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/dynamic-build-commands.graph.md](/kb/guide/dynamic-build-commands.graph.md)
<!-- /docsgraph:related -->


In this example, you'll create a `vercel.sh` file in your repository that your project's [Build Command](/docs/deployments/configure-a-build#build-command) can use to run conditional logic..

1. Set up your scripts in `package.json`. Specify the following example scripts to be run for your preview and production environments:
   
   ```json
   {
     "scripts": {
       "build:production": "next build",
       "build:preview": "echo \"Let's build a preview!\" && next build"
     }
   }
   ```
   
2. Create a `vercel.sh` file in your project's root directory. Use the following conditional logic to run a script according to the environment:
   
   ```bash
   #!/bin/bash
   
   if [[ $VERCEL_ENV == "production"  ]] ; then      npm run build:production    else      npm run build:preview    fi    ```        You can adjust this to use any other [System Environment Variables](/docs/environment-variables/system-environment-variables) on Vercel. For example, you can use `VERCEL_BRANCH_URL` to run a script according to the branch name.
   
3. Set your Build Command to use `vercel.sh` either in your `vercel.json` file or in the project dashboard:
   

- **Using a** `**vercel.json**` **file**:
  
  ```bash
  {
    "$schema": "https://openapi.vercel.sh/vercel.json",
    "buildCommand": "sh vercel.sh"
  }
  ```
  
- **Using the project dashboard**:
  
  Select your project from the [dashboard](/dashboard) and go to the **Settings** tab. Under **Build & Development Settings**, set the value of the [Build Command](/docs/deployments/configure-a-build#build-command) to be `sh vercel.sh`. This runs the `vercel.sh` script created earlier.