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:
Then, select the Settings tab:
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
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
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 thebuild
command inscripts
, 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.
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
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.
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).
Install Command
During the Build Step, Vercel attempts to install dependencies by running yarn install
(or npm install
if package-lock.json
is present) in the path you've defined in the Root Directory section.
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.
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.
Development Command
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
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 runvercel
.
Environment Variables
You can configure Environment Variables for the Build Step directly from Project Settings. Check out the Environment Variables documentation to learn more.
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
.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 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 might be slower because dependencies must be installed, but subsequent Builds will be faster.
The platform intelligently caches files based on the Framework Preset selected in your Project Settings. This typically includes files such as node_modules
, yarn.lock
, or package-lock.json
, which are cached for all. You can find the exact list for each framework by considering the cachePattern
properties within this list.
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 clear the 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 500 MB.
It is not possible to manually configure which files are cached at this time.
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
.
Git Submodules
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.
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" } } }
0.42.0
does not exist but Hugo 0.42
does exist.Build Image
The platform uses Amazon Linux 2 as the base image for the Build Step – along with several pre-installed packages.
Which packages are pre-installed on the build image?
How do I run the build image locally?
How do I install PHP on the build image?
How do I install Rust on the build image?
How do I install Go on the build image?
How do I install something else on the build image?
Related
For more information on what to do next, we recommend the following articles: