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

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

Similarly, a Vercel Function named api/user.go will be served when visiting /api/user. Visiting /api/user.go will redirect to /api/user.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"cleanUrls":true

}

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

crons

devCommand

This value overrides the Development Command in Project Settings.

Type: string | null

The devCommand 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.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"devCommand":"next dev"

}

fluid

This value allows you to enable Fluid compute programmatically.

• runtime (optional): The npm package name of a Runtime, including its version.
• memory: Memory cannot be set in vercel.json with Fluid compute enabled. Instead set it in the Functions section in your project dashboard sidebar. See setting default function memory for more information.
• maxDuration (optional): How long your Vercel Function can run on each request. Set an integer number of seconds between 1 and your plan's maximum limit. See max duration.
• supportsCancellation (optional): A boolean defining whether your Vercel Function should support request cancellation. This is only available when you're using the Node.js runtime.
• includeFiles (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 outputFileTracingIncludes in next.config.js )
• excludeFiles (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 outputFileTracingExcludes in next.config.js )
• regions (optional): An array of region identifiers specifying where this specific function should be deployed. This overrides the project-level regions setting for the matched functions. See per-function region configuration for more details.
• functionFailoverRegions (optional): An array of region identifiers specifying passive regions this specific function can fail over to during an outage. This overrides the project-level functionFailoverRegions setting for the matched functions. Enterprise only. See per-function region configuration for more details.

Description

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

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

The functions property cannot be used in combination with builds. 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 uses your project's default memory and maximum duration. See Vercel Functions limits for plan limits and defaults.

With Fluid compute enabled, set memory in the Functions section of your project dashboard, not in vercel.json. To override the maximum duration for matched functions, add the functions property.

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

This example demonstrates using the expressive value object to append the header x-authorized: true if the X-Custom-Header request header's value is prefixed by valid and ends with value.

Learn more about headers on Vercel and see limitations.

ignoreCommand

This value overrides the Ignored Build Step in Project Settings.

Type: string | null

This ignoreCommand 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.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"ignoreCommand":"git diff --quiet HEAD^ HEAD ./"

}

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

outputDirectory

This value overrides the Output Directory in Project Settings.

Type: string | null

The outputDirectory 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 build directory rather than the default public 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 vercel.json file that overrides the outputDirectory to build:

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"outputDirectory":"build"

}

exportdefaultfunctionproxy(request) {

returnnewResponse('Hello from your Routing Middleware!');

}

Runtime

An entrypoint configured through proxy runs on the Node.js runtime.

A middleware.ts file that sets runtime: 'nodejs' in its exported config behaves the same as "proxy": { "entrypoint": "middleware.ts" }.

Setting the matcher

You can set either proxy.matcher in vercel.json, or export a config object with a matcher property from your entrypoint.

The matcher accepts a single path or an array of paths:

Redirects examples

Enhancing Security for Redirects and Rewrites guide.

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

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"redirects": [

{ "source":"/me","destination":"/profile.html","permanent":false }

]

}

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

This example uses wildcard path matching to redirect requests to any path (including subdirectories) under /blog/ from your site's root to a corresponding path under /news/ 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 /posts/ that only contain numerical digits from your site's root to a corresponding path under /news/ 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 /uk/ and has x-vercel-ip-country header value of GB to a corresponding path under /uk/ relative to your site's root with a redirect status of 307:

Redirect has or missing object definition

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

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

JSONL

{"source": "/source/path", "destination": "/destination/path", "permanent": true}

{"source": "/source/path-2", "destination": "https://destination-site.com/destination/path", "permanent": true}

{"source": "https://old-domain.com/page", "destination": "/new-page", "permanent": true}

vercel dev when you configure bulkRedirectsPath in vercel.json.

Bulk redirect field definition

To improve space efficiency, all boolean values can be the single characters t (true) or f (false) while using the CSV format.

regions

This value overrides the Vercel Function Region in Project Settings.

Type: Array of region identifier String.

Valid values: List of regions, defaults to iad1.

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.

• Vercel always attempts to invoke the function in the primary region. If you specify more than one primary region in the regions 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 functionFailoverRegions, selecting the region geographically closest to the request
• The order of the regions in functionFailoverRegions 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.

Want to talk to our team?

Schedule Call

This feature is available on the Enterprise plan.

• This example rewrites requests to the path /about from your site's root to the /about-our-company.html file relative to your site's root:

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [

  { "source":"/about","destination":"/about-our-company.html" }

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

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [{ "source":"/(.*)","destination":"/index.html" }]

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

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [

  { "source":"/resize/:width/:height","destination":"/api/sharp" }

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

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [

  {

  "source":"/proxy/:match*",

  "destination":"https://example.com/:match*"

  } ] }
• 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:

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [

  {

  "source":"/:path((?!uk/).*)",

  "has": [

  {

  "type":"header",

  "key":"x-vercel-ip-country",

  "value":"GB"

  } ],

  "destination":"/uk/:path*"

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

  

  {

  "$schema":"https://openapi.vercel.sh/vercel.json",

  "rewrites": [

  {

  "source":"/dashboard",

  "missing": [

  {

  "type":"cookie",

  "key":"auth_token"

  } ],

  "destination":"/login"

  } ] }

Rewrite object definition

Rewrite has or missing object definition

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

This example demonstrates using the expressive value object to define a route that rewrites users to /end only if the X-Custom-Header header's value is prefixed by valid and ends with value.

The source 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.

has does not yet work locally while using vercel dev, but does work when deployed.

Learn more about rewrites on Vercel.

routes

The routes property lets you define routing rules using PCRE-compatible regular expressions. You can use routes alongside rewrites, redirects, headers, cleanUrls, and trailingSlash.

For common use cases, use those higher-level properties instead. See Routes vs higher-level properties for guidance on when to use each.

Type: Array of route Object.

Valid values: a list of route definitions.

Route object definition

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

This example uses the value object to define a route that only rewrites to /end if the X-Custom-Header header's value starts with valid and ends with value:

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

Transform object definition

Request path transform

The request.path transform overrides the path that the target runtime observes for a request. This is the URL path your Function reads from req.url. It does not change route selection or the destination, and it does not terminate routing. Routing continues after the override, so later routes can still match and rewrite. Adjusting the path and rewriting are separate steps, so you can do both.

Because the path is a single value rather than a named target or key, the only supported op is set, and args must be a single string:

The args value must follow these rules, otherwise the transform is rejected with an error:

• It must start with /.
• It must not be scheme-relative (no leading //host).
• It must not contain a query string.
• It must not contain whitespace or control characters. Carriage return and line feed characters are rejected as a request-smuggling guard.

You can use the same substitution support as the other transforms in args:

• Capture groups from the matched route src: numbered ( $1), named ( $name), and the built-ins $host and $wildcard.
• Environment variable expansion when the transform declares an env allowlist.

When multiple matching routes set request.path, the transform composes across them and is last-write-wins. A later request.path set overrides an earlier one. The override is included in the CDN cache key, so two requests that differ only by their request.path override are cached as separate entries.

Request path transform in a service

Within a service, a request.path transform in the service's own routes changes the path the service's runtime observes. A top-level rewrite selects which service handles a request, and the service receives the original path. A request.path transform inside the service then rewrites the path its code reads from a request, without changing what was routed.

A public request to /api/users is routed to my_backend, and the service's code observes /users. See Services routing for how the path a service sees relates to route selection.

Transform examples

In this example, you remove the incoming request header x-custom-header from all requests and responses to the /home route:

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

In this example, you append multiple values to the incoming request header x-content-type-options for all requests to the /home route:

In this example, you delete any header that begins with x-react-router- for all requests to the /home route:

In this example, you rewrite the path the runtime observes using a capture group from the matched src. A request to /articles/42 reaches the same destination, but the Function reads /posts/42 from req.url:

You can reference multiple environment variables in a single args value. List all referenced variables in the env array:

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

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

With rewrites, the regex needs to be wrapped in a capture group. The following example is equivalent to the routes usage above, but instead uses rewrites:

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"rewrites": [

{ "source":"/((?!maintenance).*)","destination":"/maintenance" }

]

}

Case sensitivity

With routes, the src property is case-insensitive, so multiple request paths with different cases serve the same page, creating duplicate content.

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

true

When trailingSlash: true, 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 /about path will redirect to /about/.

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

For example, the /about/styles.css path will not redirect, but the /about/styles path will redirect to /about/styles/.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"trailingSlash":true

}

undefined

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

For example, both /about and /about/ 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.

public

public property is no longer supported and will cause deployment failures. Remove it from your vercel.json immediately to fix broken deployments.

Remove the "public" key from your vercel.json:

{

"$schema":"https://openapi.vercel.sh/vercel.json"

}

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

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"name":"example-app"

}

version

The version property should not be used anymore.

Type: Number.

Valid values: 1, 2.

Specifies the Vercel Platform version the deployment should use.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"version":2

}

alias

The alias 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: Array or String.

Valid values: domain names (optionally including subdomains) added to the account, or a string for a suffixed URL using .vercel.app 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.

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"alias": ["my-domain.com","my-alias"]

}

scope

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

Type: String.

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 vercel secrets ls).

{

"$schema":"https://openapi.vercel.sh/vercel.json",

"scope":"my-team"

}

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

env

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

Type: Object of String keys and values.

Valid values: environment keys and values.

Environment variables passed to the invoked Vercel functions.

This example will pass the MY_KEY static env to all Vercel functions and the SECRET resolved from the my-secret-name secret dynamically.