Configuring projects with vercel.json

The file lets you configure, and override the default behavior of Vercel from within your project.

This file should be created in your project's root directory and allows you to set:

• schema autocomplete
• buildCommand
• bunVersion
• cleanUrls
• crons
• devCommand
• fluid
• framework
• functions
• headers
• ignoreCommand
• images
• installCommand
• outputDirectory
• public
• redirects
• bulkRedirectsPath
• regions
• functionFailoverRegions
• rewrites
• trailingSlash

To add autocompletion, type checking, and schema validation to your file, add the following to the top of your file:

Type:

The property can be used to override the Build Command in the Project Settings dashboard, and the script from the file for a given deployment. For more information on the default behavior of the Build Command, visit the Configure a Build - Build Command section.

This value overrides the Build Command in Project Settings.

Type:

Value:

The property configures your project to use the Bun runtime instead of Node.js. When set, all Vercel Functions and Routing Middleware not using the Edge runtime will run using the specified Bun version.

When using Next.js with ISR (Incremental Static Regeneration), you must also update your and commands in :

To learn more about using Bun with Vercel Functions, see the Bun runtime documentation.

Type: .

Default Value: .

When set to , all HTML files and Vercel functions will have their extension removed. When visiting a path that ends with the extension, a 308 response will redirect the client to the extensionless path.

For example, a static file named will be served when visiting the path. Visiting will redirect to .

Similarly, a Vercel Function named will be served when visiting . Visiting will redirect to .

If you are using Next.js and running , you will get a 404 error when visiting a route configured with locally. It does however work fine when deployed to Vercel. In the example above, visiting locally will give you a 404 with but will render correctly on Vercel.

Used to configure cron jobs for the production deployment of a project.

Type: of cron .

Limits:

• A maximum of string length of 512 for the value.
• A maximum of string length of 256 for the value.

• - Required - The path to invoke when the cron job is triggered. Must start with .
• - Required - The cron schedule expression to use for the cron job.

This value overrides the Development Command in Project Settings.

Type:

The property can be used to override the Development Command in the Project Settings dashboard. For more information on the default behavior of the Development Command, visit the Configure a Build - Development Command section.

This value allows you to enable Fluid compute programmatically.

Type:

The property allows you to test Fluid compute on a per-deployment or per custom environment basis when using branch tracking, without needing to enable Fluid in production.

This value overrides the Framework in Project Settings.

Type:

Available framework slugs:

The property can be used to override the Framework Preset in the Project Settings dashboard. The value must be a valid framework slug. For more information on the default behavior of the Framework Preset, visit the Configure a Build - Framework Preset section.

Type: of key and value .

A glob pattern that matches the paths of the Vercel functions you would like to customize:

• (matches one level e.g. but not )
• (matches all levels and )
• (matches all functions from )

• (optional): The npm package name of a Runtime, including its version.
• : Memory cannot be set in with Fluid compute enabled. Instead set it in the Functions tab of your project dashboard. See setting default function memory for more information.
• (optional): An integer defining how long your Vercel Function should be allowed to run on every request in seconds (between and the maximum limit of your plan, as mentioned below).
• (optional): A boolean defining whether your Vercel Function should support request cancellation. This is only available when you're using the Node.js runtime.
• (optional): A glob pattern to match files that should be included in your Vercel Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (Not supported in Next.js, instead use in )
• (optional): A glob pattern to match files that should be excluded from your Vercel Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (Not supported in Next.js, instead use in )

By default, no configuration is needed to deploy Vercel functions to Vercel.

For all officially supported runtimes, the only requirement is to create an directory at the root of your project directory, placing your Vercel functions inside.

The property cannot be used in combination with . Since the latter is a legacy configuration property, we recommend dropping it in favor of the new one.

Because Incremental Static Regeneration (ISR) uses Vercel functions, the same configurations apply. The ISR route can be defined using a glob pattern, and accepts the same properties as when using Vercel functions.

When deployed, each Vercel Function receives the following properties:

• Memory: 1024 MB (1 GB) - (Optional)
• Maximum Duration: 10s default - 60s / 1 minute (Hobby), 15s default - 300s / 5 minutes (Pro), or 15s default - 900s / 15 minutes (Enterprise). This can be configured up to the respective plan limit) - (Optional)

To configure them, you can add the property.

In order to use a runtime that is not officially supported, you can add a property to the definition:

In the example above, the Vercel Function does not use one of the officially supported runtimes. In turn, a property was added in order to invoke the vercel-php community runtime.

For more information on Runtimes, see the Runtimes documentation:

Type: of header .

Valid values: a list of header definitions.

This example configures custom response headers for static files, Vercel functions, and a wildcard that matches all routes.

If is an object, it has one or more of the following fields:

This example demonstrates using the expressive object to append the header if the request header's value is prefixed by and ends with .

Learn more about rewrites on Vercel and see limitations.

This value overrides the Ignored Build Step in Project Settings.

Type:

This property will override the Command for Ignoring the Build Step for a given deployment. When the command exits with code 1, the build will continue. When the command exits with 0, the build is ignored. For more information on the default behavior of the Ignore Command, visit the Ignored Build Step section.

This value overrides the Install Command in Project Settings.

Type:

The property can be used to override the Install Command in the Project Settings dashboard for a given deployment. This setting is useful for trying out a new package manager for the project. An empty string value will cause the Install Command to be skipped. For more information on the default behavior of the install command visit the Configure a Build - Install Command section.

The property defines the behavior of Vercel's native Image Optimization API, which allows on-demand optimization of images at runtime.

Type:

• - Required - Array of allowed image widths. The Image Optimization API will return an error if the parameter is not defined in this list.
• - Allow-list of local image paths which can be used with the Image Optimization API.
• - Allow-list of external domains which can be used with the Image Optimization API.
• - Cache duration (in seconds) for the optimized images.
• - Array of allowed image qualities. The Image Optimization API will return an error if the parameter is not defined in this list.
• - Supported output image formats. Allowed values are either and/or .
• - Allow SVG input image URLs. This is disabled by default for security purposes.
• - Specifies the Content Security Policy of the optimized images.
• - Specifies the value of the response header. Allowed values are or .

This value overrides the Output Directory in Project Settings.

Type:

The property can be used to override the Output Directory in the Project Settings dashboard for a given deployment.

In the following example, the deployment will look for the directory rather than the default or root directory. For more information on the default behavior of the Output Directory see the Configure a Build - Output Directory section. The following example is a file that overrides the to :

Type: .

Default Value: .

When set to , both the source view and logs view will be publicly accessible.

Type: of redirect .

Valid values: a list of redirect definitions.

This example redirects requests to the path from your site's root to the file relative to your site's root with a 307 Temporary Redirect:

This example redirects requests to the path from your site's root to the file relative to your site's root with a 308 Permanent Redirect:

This example redirects requests to the path from your site's root to the api route relative to your site's root with a 301 Moved Permanently:

This example redirects requests to the path from your site's root to the absolute path of an external site with a redirect status of 308:

This example redirects requests to all the paths (including all sub-directories and pages) from your site's root to the absolute path of an external site with a redirect status of 308:

This example uses wildcard path matching to redirect requests to any path (including subdirectories) under from your site's root to a corresponding path under relative to your site's root with a redirect status of 308:

This example uses regex path matching to redirect requests to any path under that only contain numerical digits from your site's root to a corresponding path under relative to your site's root with a redirect status of 308:

This example redirects requests to any path from your site's root that does not start with and has header value of to a corresponding path under relative to your site's root with a redirect status of 307:

If is an object, it has one or more of the following fields:

This example uses the expressive object to define a route that redirects users with a redirect status of 308 to only if the header's value is prefixed by and ends with .

Learn more about redirects on Vercel and see limitations.

Learn more about bulk redirects on Vercel and see limits and pricing.

Type: path to a file or folder.

The property can be used to import many thousands of redirects per project. These redirects do not support wildcard or header matching.

CSV, JSON, and JSONL file formats are supported, and the redirect files can be generated at build time as long as they end up in the location specified by . This can point to either a single file or a folder containing multiple redirect files.

In order to improve space efficiency, all boolean values can be the single characters (true) or (false) while using the CSV format.

This value overrides the Vercel Function Region in Project Settings.

Type: of region identifier .

Valid values: List of regions, defaults to .

You can define the regions where your Vercel functions are executed. Users on Pro and Enterprise can deploy to multiple regions. Hobby plans can select any single region. To learn more, see Configuring Regions.

Function responses can be cached in the requested regions. Selecting a Vercel Function region does not impact static files, which are deployed to every region by default.

Set this property to specify the region to which a Vercel Function should fallback when the default region(s) are unavailable.

Type: of region identifier .

Valid values: List of regions.

These regions serve as a fallback to any regions specified in the configuration. The region Vercel selects to invoke your function depends on availability and ingress. For instance:

• Vercel always attempts to invoke the function in the primary region. If you specify more than one primary region in the property, Vercel selects the region geographically closest to the request
• If all primary regions are unavailable, Vercel automatically fails over to the regions specified in , selecting the region geographically closest to the request
• The order of the regions in does not matter as Vercel automatically selects the region geographically closest to the request

To learn more about automatic failover for Vercel Functions, see Automatic failover. Vercel Functions using the Edge runtime will automatically failover with no configuration required.

Region failover is supported with Secure Compute, see Region Failover to learn more.

Type: of rewrite .

Valid values: a list of rewrite definitions.

If is set to in your project's , do not include the file extension in the source or destination path. For example, would be

• This example rewrites requests to the path from your site's root to the file relative to your site's root:

• This example rewrites all requests to the root path which is often used for a Single Page Application (SPA).

• This example rewrites requests to the paths under that with 2 paths levels (defined as variables and that can be used in the destination value) to the api route relative to your site's root:

• This example uses wildcard path matching to rewrite requests to any path (including subdirectories) under from your site's root to a corresponding path under the root of an external site :

• This example rewrites requests to any path from your site's root that does not start with /uk/ and has x-vercel-ip-country header value of GB to a corresponding path under /uk/ relative to your site's root:

• This example rewrites requests to the path from your site's root that does not have a cookie with key to the path relative to your site's root:

If is an object, it has one or more of the following fields:

This example demonstrates using the expressive object to define a route that rewrites users to only if the header's value is prefixed by and ends with .

The property should NOT be a file because precedence is given to the filesystem prior to rewrites being applied. Instead, you should rename your static file or Vercel Function.

Learn more about rewrites on Vercel.

Type: .

Default Value: .

When , visiting a path that ends with a forward slash will respond with a 308 status code and redirect to the path without the trailing slash.

For example, the path will redirect to .

When , visiting a path that does not end with a forward slash will respond with a 308 status code and redirect to the path with a trailing slash.

For example, the path will redirect to .

However, paths with a file extension will not redirect to a trailing slash.

For example, the path will not redirect, but the path will redirect to .

When , visiting a path with or without a trailing slash will not redirect.

For example, both and will serve the same content without redirecting.

This is not recommended because it could lead to search engines indexing two different pages with duplicate content.

Legacy properties are still supported for backwards compatibility, but are deprecated.

The property has been deprecated in favor of Project Linking, which allows you to link a Vercel project to your local codebase when you run .

Type: .

Valid values: string name for the deployment.

Limits:

• A maximum length of 52 characters
• Only lower case alphanumeric characters or hyphens are allowed
• Cannot begin or end with a hyphen, or contain multiple consecutive hyphens

The prefix for all new deployment instances. Vercel CLI usually generates this field automatically based on the name of the directory. But if you'd like to define it explicitly, this is the way to go.

The defined name is also used to organize the deployment into a project.

The property should not be used anymore.

Type: .

Valid values: , .

Specifies the Vercel Platform version the deployment should use.

The property should not be used anymore. To assign a custom Domain to your project, please define it in the Project Settings instead. Once your domains are, they will take precedence over the configuration property.

Type: or .

Valid values: domain names (optionally including subdomains) added to the account, or a string for a suffixed URL using or a Custom Deployment Suffix (available on the Enterprise plan).

Limit: A maximum of 64 aliases in the array.

The alias or aliases are applied automatically using Vercel for GitHub, Vercel for GitLab, or Vercel for Bitbucket when merging or pushing to the Production Branch.

You can deploy to the defined aliases using Vercel CLI by setting the production deployment environment target.

The property has been deprecated in favor of Project Linking, which allows you to link a Vercel project to your local codebase when you run .

Type: .

Valid values: For teams, either an ID or slug. For users, either a email address, username, or ID.

This property determines the scope (Hobby team or team) under which the project will be deployed by Vercel CLI.

It also affects any other actions that the user takes within the directory that contains this configuration (e.g. listing environment variables using ).

Deployments made through Git will ignore the property because the repository is already connected to project.

We recommend against using this property. To add custom environment variables to your project define them in the Project Settings.

Type: of keys and values.

Valid values: environment keys and values.

Environment variables passed to the invoked Vercel functions.

This example will pass the static env to all Vercel functions and the resolved from the secret dynamically.

We recommend against using this property. To add custom environment variables to your project define them in the Project Settings.

Type: of keys and values inside the .

Valid values: environment keys and values.

Environment variables passed to the Build processes.

The following example will pass the environment variable to all Builds and the resolved from the secret dynamically.

We recommend against using this property. To customize Vercel functions, please use the functions property instead. If you'd like to deploy a monorepo, see the Monorepo docs.

Type: of build .

Valid values: a list of build descriptions whose references valid source files.

• (): A glob expression or pathname. If more than one file is resolved, one build will be created per matched file. It can include and .
• (): An npm module to be installed by the build process. It can include a semver compatible version (e.g.: ).
• (): Optionally, an object including arbitrary metadata to be passed to the Builder.

The following will include all HTML files as-is (to be served statically), and build all Python files and JS files into Vercel functions:

When at least one item is specified, only the outputs of the build processes will be included in the resulting deployment as a security precaution. This is why we need to allowlist static files explicitly with .

We recommend using cleanUrls, trailingSlash, redirects, rewrites, and/or headers instead.

The property is only meant to be used for advanced integration purposes, such as the Build Output API, and cannot be used in conjunction with any of the properties mentioned above.

See the upgrading routes section to learn how to migrate away from this property.

Type: of route .

Valid values: a list of route definitions.

• : A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
• : A set of HTTP method types. If no method is provided, requests with any HTTP method will be a candidate for the route.
• : A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2…
• : A set of headers to apply for responses.
• : A status code to respond with. Can be used in tandem with header to implement redirects.
• : A boolean to change matching behavior. If , routing will continue even when the is matched.
• : An optional array of objects with the , and properties. Used for conditional path matching based on the presence of specified properties
• : An optional array of objects with the , and properties. Used for conditional path matching based on the absence of specified properties
• : An optional object with the property , which can either be "challenge" or "deny". These perform mitigation actions on requests that match the route.
• : An optional array of objects to apply. Transform rules let you append, set, or remove request/response headers and query parameters at the edge so you can enforce security headers, inject analytics tags, or personalize content without touching your application code. See examples below.

Routes are processed in the order they are defined in the array, so wildcard/catch-all patterns should usually be last.

If is an object, it has one or more of the following fields:

This example uses the expressive object to define a route that will only rewrite users to if the header's value is prefixed by and ends with :

This example configures custom routes that map to static files and Vercel functions:

Target is an object with a property. For the operation, the property is used as the header or query key. For other operations, it is used as a matching condition to determine if the transform should be applied.

When the property is an object, it can contain one or more of the following conditional matching properties:

These examples demonstrate practical use-cases for route transforms.

In this example, you remove the incoming request header from all requests and responses to the route:

In this example, you override the incoming query parameter to for all requests to the route, and set if it doesn't already exist:

In this example, you append multiple values to the incoming request header for all requests to the route:

In this example, you delete any header that begins with for all requests to the route:

You can integrate transforms with existing matching capabilities through the and properties for routes, along with using expressive matching conditions through the Transform key object definition.

In most cases, you can upgrade legacy usage to the newer , , , or properties.

Here are some examples that show how to upgrade legacy to the equivalent new property.

With , you use a PCRE Regex named group to match the ID and then pass that parameter in the query string. The following example matches a URL like and proxies to :

With , named parameters are automatically passed in the query string. The following example is equivalent to the legacy usage above, but uses instead:

With , you specify the status code to use a 307 Temporary Redirect. Also, this redirect needs to be defined before other routes. The following example redirects all paths in the directory to the directory, but keeps the path in the new location:

With , you disable the property to use a 307 Temporary Redirect. Also, are always processed before . The following example is equivalent to the legacy usage above, but uses instead:

With , you use to give precedence to the filesystem and exit early if the requested path matched a file. The following example will serve the file for all paths that do not match a file in the filesystem:

With , the filesystem check is the default behavior. If you want to change the name of files at the filesystem level, file renames can be performed during the Build Step, but not with . The following example is equivalent to the legacy usage above, but uses instead:

With , you use to prevent stopping at the first match. The following example adds headers to the favicon and other static assets:

With , this is no longer necessary since that is the default behavior. The following example is equivalent to the legacy usage above, but uses instead:

With , you need to escape a dot with two backslashes, otherwise it would match any character PCRE Regex. The following example matches the literal and proxies to to dynamically generate RSS:

With , the is not a special character so it does not need to be escaped. The following example is equivalent to the legacy usage above, but instead uses :

With , you use PCRE Regex negative lookahead. The following example proxies all requests to the page except for itself to avoid infinite loop:

With , the Regex needs to be wrapped. The following example is equivalent to the legacy usage above, but instead uses :

With , the property is case-insensitive leading to duplicate content, where multiple request paths with difference cases serve the same page.

With / / , the property is case-sensitive so you don't accidentally create duplicate content.