When you trigger a deploy, Vercel builds your project. For many frontend frameworks, Vercel automatically configures the build settings, but you can also customize them. You can also use environment variables to avoid hardcoding values.

Customizing Build Settings

To customize the build settings for your project, choose a project from the dashboard:

Selecting the project from the Vercel Dashboard.

Then, select the Settings tab:

Selecting the Settings tab from the Project Overview page.

You can then edit the build settings from the Build & Development Settings, Root Directory, and Environment Variables sections.

Build & Development Settings

Vercel tries to automatically detect the frontend framework you’re using for your project and configure the project settings for you. If you’d like to override the settings or specify a different framework, you can do so from the Build & Development Settings section.

Framework Preset

The Framework Preset setting.

Vercel detects the following frontend frameworks automatically and chooses the best default settings for you.

If no framework is detected, "Other" will be selected for you.

You can always choose a different framework preset or "Other" if you’d like.

Build Command

The Build Command setting.

If Vercel detects a framework, the Build Command will automatically be configured. Depending on a framework, the Build Command can refer to the project’s configuration file.

For example, if you choose Next.js, here’s what happens by default:

  • If package.json contains the build command in scripts, this command will be used to build the project.
  • If not, next build will be the Build Command.

If you’d like to override the Build Command, you can turn on the Override toggle and specify the command.

Note: If you update this setting, it will be applied starting with your next deployment.
Skip Build Step

Some static projects do not require building. An example of this would be a website with only HTML/CSS/JS source files that can be served as-is (For example, you might just have a single index.html file).

In such cases, you should:

  • Specify "Other" as the framework preset, and
  • Enable the Override option for the Build Command, and
  • Leave the Build Command empty.

This will prevent the build from being attempted and serve your content as-is.

Output Directory

The Output Directory setting.

After building a project, most frameworks will output the result in a directory. Contents in this output directory will be the only things that will be statically served by Vercel.

If Vercel detects a framework, the output directory will automatically be configured.

Note: If you update this setting, it will be applied starting with your next deployment.

In some cases, your project might not require building, and you might just want to serve the files in the root directory. If so, try the following:

  • Choose "Other" as the framework preset. If you do so, by default, the output directory will be set as public if it exists, or . (current directory) otherwise.
  • Therefore, as long as your project doesn’t have the public directory, it will serve the files in the root directory.
  • Alternatively, you can turn on the Override toggle and leave the field empty (in which case, the build step will be skipped).

Development Command

The Development Command setting.

Note: This setting is relevant only if you’re using vercel dev locally to develop your project. You should be using vercel dev only if you need to use a Vercel platform feature like Serverless Functions. In other cases, you should use the development command your framework provides (such as next dev for Next.js).

The Development Command setting allows you to customize the behavior of vercel dev. If Vercel detects a framework, the development command will automatically be configured.

If you’d like to use a custom command for vercel dev, you can turn on the Override toggle. Please note the following:

  • If you specify a custom command, your command must pass the $PORT variable (which contains the port number) to your framework. For example, for Next.js, you should use: next dev --port $PORT.
  • If the development command is not specified, vercel dev will fail. If you selected "Other" as the framework preset, the development command will be empty by default.
  • You must create a deployment and have your local project be linked to the project on Vercel (using vercel). Otherwise, vercel dev won’t work correctly.

Root Directory

The Root Directory setting.

In some projects, the top-level directory of the repository may not be the root directory of the app you’d like to build. For example, your repository might have a frontend directory, which contains a stand-alone Next.js app.

In cases like this, you can specify the project root directory. If you do so, please note the following:

  • If you specify a root directory, then your app won’t be able to access files outside of that directory. You also cannot use .. to move up a level.
  • This setting also applies to Vercel CLI. Instead of running vercel <directory-name> to deploy, specify <directory-name> here so you can just run vercel.
Note: If you update this setting, it will be applied starting with your next deployment.

Environment Variables

Environment Variables are accessible during both Build Step and Runtime, and can be configured for Production, Preview, and Development Environments individually.

This allows you to include values that you don't want to share in your code or to change the behavior of your code depending on its Environment.

To declare an Environment Variable for your deployment, head to the General page of your Project Settings and locate the Environment Variables section.

The Environment Variables settings.

First, choose between the following Environments:

Environment
Description
Production
When selected, the Environment Variable will be applied to your next Production Deployment. To create a Production Deployment, push a commit to the default branch or run vercel --prod.
Preview
The Environment Variable is applied to your next Preview Deployment. Preview Deployments are created when you push to a branch (for example, my-new-feature) or run vercel.
Development
The Environment Variable is for use when running your project locally, with vercel dev or your preferred development command. To download Development Environment Variables, run vercel env pull.

Enter the Name of the Environment Variable. For example, if you are using Node.js and you create an Environment Variable named SENTRY_KEY, it will be available under process.env.SENTRY_KEY in your code.

Then, enter the Value of the Environment Variable. The value is automatically encrypted and stored as a Secret in our system when you click Add.

Adding an Environment Variable in the Project Settings.

Once added, the Environment Variable is applied to your subsequent deployment. It can then be consumed during Build Step by the framework of your choice, or by a Serverless Function at Runtime.

Note: If any Environment Variables differ between Deployments, deduplication will always be bypassed. For example, this means that merging to the default branch will no longer result in an instant deployment.

Development Environment Variables

Environment Variables created for the Development Environment can be downloaded into a local development setup using the vercel env pull command provided by Vercel CLI:

vercel env pull
Downloading Development Environment Variables for project my-lovely-project
✅ Created .env file [510ms]

Downloading Development Environment Variables with `vercel env pull`.

Running the command will create a .env file in your project folder. The .env file can then be consumed by vercel dev or your preferred development command.

Check out the Vercel CLI reference to learn more about vercel env commands.

Integration Environment Variables

Integrations can automatically add Environment Variables to your Project Settings. In that case, the Integration Configuration that added it will be displayed:

Adding an Integration Environment Variable in the Project Settings.

Note: Support for Integration Environment Variables was added on April 10th, 2020. Variables added before that date do not have the Integration indication.

System Environment Variables

Vercel provides a set of Environment Variables that are optionally populated by the System, such as the URL of the Deployment or the name of the Git branch deployed.

To apply a System Environment Variable to your Deployment, enter its Name, leave the Value empty, and click Add.

Adding a System Environment Variable in the Project Settings.

The following System Environment Variables are available:

Name
Description
VERCEL_URL
The URL of the deployment. Example: my-site-7q03y4pi5.vercel.app.
VERCEL_GITHUB_DEPLOYMENT
An indicator for whether the app was deployed by Vercel for GitHub. Example: 1.
VERCEL_GITHUB_ORG
The GitHub organization that owns the repository the deployment is triggered from. Example: acme.
VERCEL_GITHUB_REPO
The origin repository of the app on GitHub. Example: my-site.
VERCEL_GITHUB_COMMIT_ORG
The GitHub organization of which the commit belongs. For example, when submitting a pull request from a forked repository. Example: acme.
VERCEL_GITHUB_COMMIT_REPO
The GitHub repository of which the commit belongs. For example, when submitting a pull request from a forked repository. Example: my-site.
VERCEL_GITHUB_COMMIT_REF
The GitHub branch that the deployment was made from. Example: improve-about-page.
VERCEL_GITHUB_COMMIT_SHA
The GitHub SHA of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
VERCEL_GITHUB_COMMIT_AUTHOR_LOGIN
The GitHub username belonging to the author of the commit that the project was deployed by. Example: johndoe.
VERCEL_GITHUB_COMMIT_AUTHOR_NAME
The GitHub name belonging to the author of the commit that the project was deployed by. Example: John Doe.
VERCEL_GITLAB_DEPLOYMENT
An indicator for whether the app was deployed by Vercel for GitLab. Example: 1.
VERCEL_GITLAB_PROJECT_NAMESPACE
The GitLab user, group, or sub-group that the project belongs to. Example: Acme.
VERCEL_GITLAB_PROJECT_NAME
The GitLab name of the deployed project. Example: my-site.
VERCEL_GITLAB_PROJECT_ID
The GitLab ID of the deployed project. Example: 13343236.
VERCEL_GITLAB_PROJECT_PATH
The GitLab project path. Example: acme/my-site.
VERCEL_GITLAB_COMMIT_REF
The GitLab branch that the deployment was triggered by. Example: improve-about-page.
VERCEL_GITLAB_COMMIT_SHA
The GitLab sha of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
VERCEL_GITLAB_COMMIT_MESSAGE
The message accompanying the GitLab commit that the deployment was triggered by. Example: Add John Doe to about page.
VERCEL_GITLAB_COMMIT_AUTHOR_LOGIN
The username belonging to the author of the commit that was deployed on GitLab. Example: johndoe.
VERCEL_GITLAB_COMMIT_AUTHOR_NAME
The name belonging to the author of the commit that was deployed on GitLab. Example: John Doe.
VERCEL_BITBUCKET_DEPLOYMENT
An indicator for whether the app was deployed by Vercel for Bitbucket. Example: 1.
VERCEL_BITBUCKET_REPO_OWNER
The Bitbucket user or team that the project belongs to. Example: acme.
VERCEL_BITBUCKET_REPO_SLUG
The slug of the Bitbucket repository that was deployed. Example: my-site.
VERCEL_BITBUCKET_REPO_NAME
The name of the Bitbucket repository that was deployed. Example: my-site.
VERCEL_BITBUCKET_COMMIT_REF
The Bitbucket branch that the deployment was triggered by. Example: improve-about-page.
VERCEL_BITBUCKET_COMMIT_SHA
The Bitbucket sha of the commit the deployment was triggered by. Example: fa1eade47b73733d6312d5abfad33ce9e4068081.
VERCEL_BITBUCKET_COMMIT_MESSAGE
The message accompanying the Bitbucket commit that was deployed. Example: Add John Doe to about page.
VERCEL_BITBUCKET_COMMIT_AUTHOR_NAME
The name of the commit author on Bitbucket. Example: John Doe.
VERCEL_BITBUCKET_COMMIT_AUTHOR_URL
Bitbucket profile URL of the commit author. Example: https://bitbucket.org/%7B45585b19-b616-401e-89d3-1a47fddb7033%7D/.

Reserved Environment Variables

The Vercel platform reserves the usage of some Environment Variable names by default. You can find a list of these names in the limits documentation.

Ignored Files and Folders

By default, Vercel ignores certain files and folders for security and performance reasons, preventing them from being uploaded during the deployment process.

.hg/
.git/
.gitmodules
.svn/
.cache
.next/
.now/
.vercel/
.npmignore
.dockerignore
.gitignore
.*.swp
.DS_Store
.wafpicke-*
.lock-wscript
.env.local
.env.*.local
.venv
npm-debug.log
config.gypi
node_modules/
__pycache__/
venv/
CVS

A complete list of files and folders ignored by Vercel during the deployment process.

Note: You do not need to add any of the above files and folders to your .vercelignore file.

Technical Details

Maximum Build Duration

A build can last for a maximum of 30 minutes. If the build exceeds this time, the deployment will error.

Caching

Each build step will cache files used to build the project, or files used in subsequent deployments, such as node_modules, yarn.lock, package-lock.json, which are cached by default.

The caching mechanism for builds ensures that the next deployment will happen quicker by skipping downloading files that have already been used in a previous deployment.

The maximum stored cache for builds is 500MB.

If a deployment fails, a cache may still be established for successfully built files, but failed builds will not be cached.

Private npm Modules for Static Builds

To install private npm modules, define NPM_TOKEN as a build environment variable in a vercel.json file.

Alternatively, define NPM_RC as a build environment variable with the contents of ~/.npmrc.

Prevent Installing Development Dependencies

In some rare cases, you may wish to skip installing devDependencies defined in your package.json file and only install dependencies.

This can be achieved by assigning NPM_ONLY_PRODUCTION=1 as a build environment variable.

This is equivalent to npm install --only=production or yarn install --production.

Prevent Cache Usage

If you need to ignore the cache for a deployment, you can do so by using the -f flag for Vercel CLI. This prevents the cache from being used in the deployment and ensures a fresh install for all dependencies.

Framework Versioning

Some frameworks do not use package.json to select a specific version to install during build time.

By including a build.env configuration property in a vercel.json file at your project's root, you can define your framework's version with one of the following keys:

Framework
Build Env Key
Hugo
HUGO_VERSION
Zola
ZOLA_VERSION

For example, defining the Hugo version in a vercel.json file would look like the following snippet:

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.61.0"
    }
  }
}

An example of defining a version for Hugo with a vercel.json configuration.

Note: The value must match an existing GitHub Release with an attached asset. For example, Hugo 0.42.0 does not exist but Hugo 0.42 does exist.

Related

For more information on what to do next, we recommend the following articles: