When you trigger a deployment, Vercel builds your project. During the build step, Vercel performs a "shallow clone" on your Git repository by using the command git clone --depth=10 (...) to fetch ten levels of git commit history. This way, Vercel pulls only the latest ten commits and not the entire repo history.

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.

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.

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.

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.

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.

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).

The Install Command setting.

During the Build Step, Vercel attempts to install dependencies by running pnpm install if pnpm-lock.yaml is present, npm install if package-lock.json is present, or yarn install by default in the path you've defined in the Root Directory section.

Note: npm v8 will be used when your deployment's package-lock.json file contains lockfileVersion 2 or greater and pnpm v7 will be used when your deployment's pnpm-lock.yaml file contains lockfileVersion 5.4.

This will automatically install all dependencies defined in package.json (even devDependencies, which can be excluded like this).

If you’d like to override the Install 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.
Custom Install Command for Your API

If you're using a frontend framework that also supports Serverless Functions for APIs, the Install Command defined in the Project Settings will be used.

In the case that you're using Serverless Functions that were defined in the natively supported api directory, however, a different Install Command will be used depending on the language of the Serverless Function. For those, it cannot be customized.

The Development Command setting.

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.

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.

When making multiple deployments with Vercel, the builds can get queued. A Vercel Hobby account has access to a single concurrent build slot by default. This means that only one deployment can be built at any one time unless additional concurrent build slots are purchased. All other deployments will be put into a queue and build one after another.

Team accounts can increase the number of Concurrent Builds in the Billing section of their Team Settings page, allowing the Team to create Deployments faster.

  • Personal Accounts cannot increase their Concurrent Builds limit.
  • The maximum number of Concurrent Builds for a Team is 12.
  • For Enterprise accounts, contact sales to get custom number of concurrent builds.

Setting the Concurrent Builds limit for a Team.

Note: You can add only three builds until your Team is under a 14-day trial. Once you add a payment method, you can upgrade it to 12 slots.

You can configure Environment Variables for the Build Step directly from Project Settings. Check out the Environment Variables documentation to learn more.

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


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.

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

Vercel intelligently caches files based on the Framework Preset selected in your Project Settings. The following files are cached in addition to node_modules/**:

Cache Pattern

Each Deployment contains one or more separate Builds, and each type of Build has a dedicated cache. Together, they are the "Build Step".

The Build's cache key is derived from the combination of the following data:

At the beginning of each Build, the previous Build's cache is restored prior to the Install Command or Build Command executing. This means that your first Build for a given Project might be slower because dependencies must be installed, but subsequent Builds will be faster.

When a new Git branch is created, there will not be a cache for that specific branch. Instead, the last Production Deployment cache will be used and a new branch cache will be created.

Serverless Functions also have their own cache within the Build Step, defined by the Runtime that is used.

At the end of each Build Step, successful Builds will update the cache and failed Builds will not modify the existing cache.

Deployments made using the "Redeploy" button on the Dashboard or using vercel --force on Vercel CLI will also delete any previously successful Build's cache prior to starting the Build Step of the new Deployment.

The maximum size of a Build's cache is 1 GB and is retained for one month.

It is not possible to manually configure which files are cached at this time.

Every Build is provided with 8192 MiB of memory.

To install private npm modules, define NPM_TOKEN as an Environment Variable in your Project.

Alternatively, define NPM_RC as an Environment Variable with the contents of ~/.npmrc.

Deploying Git submodules with a Git provider is supported as long as the submodule is publicly accessible via the HTTP protocol. Git submodules that are private or requested over SSH will fail during the Build step.

You can customize the Install Command to be npm install --only=production or yarn install --production in order to install only production dependencies and skip development dependencies.

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.

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

By including an Environment Variable, you can define your framework's version with one of the following:

Environment Variable Name

For example, to select Hugo v0.92.2 you would add an Environment Variable named HUGO_VERSION with value 0.92.2.

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

The platform uses Amazon Linux 2 as the base image for the Build Step – along with several pre-installed packages.

Note: These packages are only available during the Build Step and not during runtime.

The following packages have already been installed with yum (the default package manager for Amazon Linux 2) on the build image:
  • alsa-lib
  • at-spi2-atk
  • atk
  • autoconf
  • automake: 1.13.4
  • bsdtar
  • bzip2
  • bzip2-devel
  • cups-libs
  • expat-devel
  • gcc
  • gcc-c++
  • gifsicle: 1.91
  • git
  • glib2-devel
  • glibc-devel
  • gtk3
  • gzip
  • ImageMagick-devel
  • java-11-amazon-corretto-headless
  • libXScrnSaver
  • libXcomposite
  • libXcursor
  • libXi
  • libXrandr
  • libXtst
  • libffi-devel
  • libglvnd-glx
  • libicu
  • libjpeg
  • libjpeg-devel
  • libpng
  • libpng-devel
  • libstdc++
  • libwebp-tools
  • make
  • ncurses-libs
  • openssl
  • openssl-devel
  • openssl-libs
  • pango
  • readline-devel
  • ruby-devel
  • strace
  • tar
  • unzip
  • which
  • zlib-devel

To get started with Amazon Linux 2 locally, run the following command:

docker run --rm -it amazonlinux:2.0.20191217.0 sh
Once you're done, run exit to stop executing it.

To make php available in your Build Step, add the following to your Build Command:

amazon-linux-extras install php7.4
You can learn more about Amazon Linux Extras here.

To make cargo available in your Build Step, add the following to your Build Command:

amazon-linux-extras install rust1
You can learn more about Amazon Linux Extras here.

To make go available in your Build Step, add the following to your Build Command:

amazon-linux-extras install golang1.11
You can learn more about Amazon Linux Extras here.

The build image includes access to repositories with stable versions of popular packages.

You can list all packages by adding the following to your Build Command:

yum list
You can search for a package by name with the following:
yum search my-package-here
You can install a package by name with the following:
yum install my-package-here -y
If you need a new software package or a newer version of an existing software package that is not included in the default repositories, you can use Amazon Linux Extras.

You can list extra packages with the following:
You can install extra packages with the following:
amazon-linux-extras install my-package-here

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