The vercel.json configuration file lets you configure, and override the default behavior of Vercel from within your project. This includes settings for:

• buildCommand
• cleanUrls
• devCommand
• framework
• functions
• headers
• ignoreCommand
• installCommand
• outputDirectory
• public
• redirects
• regions
• rewrites
• trailingSlash

buildCommand

Type: string | null

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

{
  "buildCommand": "next build"
}

Example vercel.json that overrides the buildCommand to next build

cleanUrls

Type: Boolean.

Default Value: false.

When set to true, all HTML files and Serverless 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 about.html will be served when visiting the /about path. Visiting /about.html will redirect to /about.

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

{
  "cleanUrls": true
}

devCommand

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.

{
  "devCommand": "next dev"
}

Example vercel.json that overrides the devCommand to next dev

framework

Type: string | null

Available framework slugs:

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

{
  "framework": "nextjs"
}

Example vercel.json that overrides the framework to nextjs

functions

Type: Object of key String and value Object.

Key definition

A glob pattern that matches the paths of the Serverless Functions you would like to customize:

• api/*.js (matches one level e.g. api/hello.js but not api/hello/world.js)
• api/**/*.ts (matches all levels api/hello.ts and api/hello/world.ts)
• src/pages/**/* (matches all functions from src/pages)
• api/test.js

Value definition

• runtime (optional): The npm package name of a Runtime, including its version.
• memory (optional): An integer defining the memory in MB for your Serverless Function (between 128 and 3008, in intervals of 64).
• maxDuration (optional): An integer defining how long your Serverless Function should be allowed to run on every request in seconds (between 1 and the maximum limit of your plan, as mentioned below).
• includeFiles (optional): A glob pattern to match files that should be included in your Serverless Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (does not apply if Next.js is used)
• excludeFiles (optional): A glob pattern to match files that should be excluded from your Serverless Function. If you’re using a Community Runtime, the behavior might vary. Please consult its documentation for more details. (does not apply if Next.js is used)

Description

By default, no configuration is needed to deploy Serverless 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 Serverless 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.

When deployed, each Serverless Function receives the following properties:

• Memory: 1024 MB (1 GB) - (Optional)
• Maximum Execution Duration: 10s (Hobby), 60s (Pro), or 900s (Enterprise) - (Optional)

To configure them, you can add the functions property.

functions property with Serverless Functions

{
  "functions": {
    "api/test.js": {
      "memory": 3008,
      "maxDuration": 30
    },
    "api/*.js": {
      "memory": 3008,
      "maxDuration": 30
    }
  }
}

functions property with ISR

{
  "functions": {
    "pages/blog/[hello].tsx": {
      "memory": 1024
    },
    "src/pages/isr/**/*": {
      "maxDuration": 10
    }
  }
}

Using unsupported runtimes

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

{
  "functions": {
    "api/test.php": {
      "runtime": "vercel-php@0.1.0"
    }
  }
}

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

For more information on Runtimes, see the documentation:

headers

Used to attach headers to HTTP responses from your Deployments.

Headers do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of header Object.

Valid values: a list of header definitions.

Limits:

• A maximum of 1,024 headers in the array.
• A maximum of string length of 4,096 for the source, key, and value values.

Header object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• headers: An non-empty array of key/value pairs representing each response header.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

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

{
  "headers": [
    {
      "source": "/service-worker.js",
      "headers" : [
        {
          "key" : "Cache-Control",
          "value" : "public, max-age=0, must-revalidate"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers" : [
        {
          "key" : "X-Content-Type-Options",
          "value" : "nosniff"
        },
        {
          "key" : "X-Frame-Options",
          "value" : "DENY"
        },
        {
          "key" : "X-XSS-Protection",
          "value" : "1; mode=block"
        }
      ]
    },
    {
      "source": "/:path*",
      "has": [
        {
          "type": "query",
          "key": "authorized"
        }
      ],
      "headers": [
        {
          "key": "x-authorized",
          "value": "true"
        }
      ]
    }
  ]
}

ignoreCommand

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.

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

Example vercel.json that overrides the ignoreCommand to git diff --quiet HEAD^ HEAD ./

installCommand

Type: string | null

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

{
  "installCommand": "pnpm install"
}

Example vercel.json that overrides the installCommand to pnpm install

outputDirectory

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 visit the Configure a Build - Output Directory section.

{
  "outputDirectory": "build"
}

Example vercel.json that overrides the outputDirectory to build

public

Type: Boolean.

Default Value: false.

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

{
  "public": true
}

redirects

Redirects allow you to send users to URLs that are different from the ones they originally requested. For example, if you rename existing public routes in your application, adding redirects ensures there are no broken links for your users.

They are framework agnostic. You can use them with any framework on the Vercel platform. If you are using Next.js, it is recommended to continue using framework level redirects as they have precedence over platform level redirects.

Redirects do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of redirect Object.

Valid values: a list of redirect definitions.

Limits:

• A maximum of 1,024 redirects in the array.
• A maximum of string length of 4,096 for the source and destination values.

Redirect object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• destination: A location destination defined as an absolute pathname or external URL.
• permanent: A boolean to toggle between permanent and temporary redirect (default true). When true, the status code is 308. When false the status code is 307.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

{
  "redirects": [
    { "source": "/me", "destination": "/profile.html" },
    { "source": "/user", "destination": "/api/user", "permanent": false },
    { "source": "/view-source", "destination": "https://github.com/vercel/vercel" },
    {
      "source": "/:path((?!uk/).*)",
      "has": [
        {
          "type": "header",
          "key": "x-vercel-ip-country",
          "value": "GB"
        }
      ],
      "destination": "/uk/:path*",
      "permanent": false
    }
  ]
}

Example vercel.json that redirects /me to a static file, /user to a Serverless Function, /view-source to an external URL, and UK visitors to the UK localized path.

In some rare cases, you might need to assign a custom status code for older HTTP Clients to properly redirect. In these cases, you can use the statusCode property instead of the permanent property, but not both.

regions

Type: Array of region identifier String.

Valid values: List of regions, defaults to iad1.

Select the deployment regions of Serverless Functions in your application. Deploying to multiple regions (or all) is limited to Enterprise plans, but Pro and Hobby plans can select any single region.

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

{
  "regions": ["sfo1"]
}

rewrites

Rewrites allow you to send users to different URLs without modifying the visible URL. This is also known as a URL proxy.

You can also use them to return different responses depending on the headers of the incoming request (such as User-Agent, which contains the type of device and browser that the request originated from).

Rewrites do not require a Serverless Function and can be directly processed at the Edge across all regions.

Type: Array of rewrite Object.

Valid values: a list of rewrite definitions.

Limits:

• A maximum of 1,024 rewrites in the array.
• A maximum of string length of 4,096 for the source and destination values.

Rewrite object definition:

• source: A pattern that matches each incoming pathname (excluding querystring).
• destination: An absolute pathname to an existing resource or an external URL.
• has: An optional array of has objects with the type, key and value properties.
  • type: String — must be either header, cookie, host, or query.
  • key: String — the key from the selected type to match against.
  • value: String or not defined — the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the value first-(?<paramName>.*) is used for first-second then second will be usable in the destination with :paramName.

{
  "rewrites": [
    { "source": "/about", "destination": "/about-our-company.html" },
    { "source": "/resize/:width/:height", "destination": "/api/sharp" },
    { "source": "/proxy/:match*", "destination": "https://example.com/:match*" },
    {
      "source": "/:path((?!uk/).*)",
      "has": [
        {
          "type": "header",
          "key": "x-vercel-ip-country",
          "value": "GB"
        }
      ],
      "destination": "/uk/:path*"
    }
  ]
}

Example vercel.json that rewrites /about to a static file, /resize/100/50 to /api/sharp?width=100&height=50, /proxy/support to https://example.com/support, and UK visitors to the UK localized path.

trailingSlash

Type: Boolean.

Default Value: undefined.

false

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

{
  "trailingSlash": false
}

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

{
  "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.

Legacy

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

name

Type: String.

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.

{
  "name": "example-app"
}

version

Type: Number.

Valid values: 1, 2.

Specifies the

{
  "version": 2
}

alias

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.

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

scope

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 (Personal Account or Team) under which the project will be deployed by Vercel CLI.

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

{
  "scope": "my-team"
}

env

Type: Object of String keys and values.

Valid values: environment keys and values.

Environment variables passed to the invoked Serverless Functions.

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

{
  "env": {
    "MY_KEY": "this is the value",
    "SECRET": "@my-secret-name"
  }
}

build.env

Type: Object of String keys and values inside the build Object.

Valid values: environment keys and values.

Environment variables passed to the Build processes.

The following example will pass the MY_KEY Environment Variable to all Builds and SECRET resolved from the my-secret-name Secret dynamically.

{
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}

builds

Type: Array of build Object.

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

Build object definition:

• src (String): A glob expression or pathname. If more than one file is resolved, one build will be created per matched file. It can include * and **.
• use (String): An npm module to be installed by the build process. It can include a semver compatible version (e.g.: @org/proj@1).
• config (Object): 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 Serverless Functions:

{
  "builds": [
    { "src": "*.html", "use": "@vercel/static" },
    { "src": "*.py", "use": "@vercel/python" },
    { "src": "*.js", "use": "@vercel/node" }
  ]
}

routes

Type: Array of route Object.

Valid values: a list of route definitions.

Route object definition:

• src: A PCRE-compatible regular expression that matches each incoming pathname (excluding querystring).
• methods: A set of HTTP method types. If no method is provided, requests with any HTTP method will be a candidate for the route.
• dest: A destination pathname or full URL, including querystring, with the ability to embed capture groups as $1, $2…
• headers: A set of headers to apply for responses.
• status: A status code to respond with. Can be used in tandem with Location: header to implement redirects.
• continue: A boolean to change matching behavior. If true, routing will continue even when the src is matched.

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

This example configures custom routes that map to static files and Serverless Functions:

{
  "routes": [
    { "src": "/redirect", "status": 308, "headers": { "Location": "https://example.com/" } },
    { "src": "/custom-page", "headers": {"cache-control": "s-maxage=1000"}, "dest": "/index.html" },
    { "src": "/api", "dest": "/my-api.js" },
    { "src": "/users", "methods": ["POST"], "dest": "/users-api.js" },
    { "src": "/users/(?<id>[^/]*)", "dest": "/users-api.js?id=$id" },
    { "src": "/legacy", "status": 404},
    { "src": "/.*", "dest": "https://my-old-site.com"}
  ]
}

Upgrading

In most cases, you can upgrade legacy routes usage to the newer rewrites, redirects, headers, cleanUrls or trailingSlash properties.

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

Route Parameters

With routes, you use a PCRE Regex named group to match the ID and then pass that parameter in the query string.

{
  "routes": [{ "src": "/product/(?<id>[^/]+)", "dest": "/api/product?id=$id" }]
}

Match URL like /product/532004 and proxy to /api/product?id=532004.

With rewrites, named parameters are automatically passed in the query string.

{
  "rewrites": [{ "source": "/product/:id", "destination": "/api/product" }]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Redirects

With routes, you specify the status code to use a 307 Temporary Redirect. Also, this redirect needs to be defined before other routes.

{
  "routes": [
    {
      "src": "/posts/(.*)",
      "headers": { "Location": "/blog/$1" },
      "status": 307
    }
  ]
}

Redirecting from all paths in the posts directory but keeping the path in the new location.

With redirects, you disable the permanent property to use a 307 Temporary Redirect. Also, redirects are always processed before rewrites.

{
  "redirects": [
    {
      "source": "/posts/:id",
      "destination": "/blog/:id",
      "permanent": false
    }
  ]
}

Equivalent to the legacy routes usage above, but instead using redirects.

SPA Fallback

With routes, you use "handle": "filesystem" to give precedence to the filesystem and exit early if the requested path matched a file.

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/index.html" }
  ]
}

Fallback to index.html after checking the filesystem for exact matches.

With rewrites, 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 rewrites.

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

Equivalent to the legacy routes usage above, but instead using rewrites.

Headers

With routes, you use "continue": true to prevent stopping at the first match.

{
  "routes": [
    {
      "src": "/favicon.ico",
      "headers": { "Cache-Control": "public, max-age=3600" },
      "continue": true
    },
    {
      "src": "/assets/(.*)",
      "headers": { "Cache-Control": "public, max-age=31556952, immutable" },
      "continue": true
    }
  ]
}

Add Cache-Control headers to favicon and other static assets.

With headers, this is no longer necessary since that is the default behavior.

{
  "headers": [
    {
      "source": "/favicon.ico",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    },
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31556952, immutable"
        }
      ]
    }
  ]
}

Equivalent to the legacy routes usage above, but instead using headers.

Pattern Matching

With routes, you need to escape a dot with two backslashes, otherwise it would match any character PCRE Regex.

{
  "routes": [{ "src": "/atom\\.xml", "dest": "/api/rss" }]
}

Match the literal /atom.xml and proxy to /api/rss to dynamically generate RSS.

With rewrites, the . is not a special character so it does not need to be escaped.

{
  "rewrites": [{ "source": "/atom.xml", "destination": "/api/rss" }]
}

Equivalent to the legacy routes usage above, but instead using rewrites.

Negative Lookahead

With routes, you use PCRE Regex negative lookahead.

{
  "routes": [{ "src": "/(?!maintenance)", "dest": "/maintenance" }]
}

Proxy all requests to the /maintenance except for /maintenance directly to avoid infinite loop.

With rewrites, the Regex needs to be wrapped.

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

Equivalent to the legacy routes usage above, but instead using rewrites.

Case Sensitivity

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

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

Git Configuration

The following configuration options can be used through a vercel.json file like the options above.

github.enabled

Type: Boolean.

When set to false, Vercel for GitHub will not deploy the given project regardless of the GitHub app being installed.

{
  "github": {
    "enabled": false
  }
}

github.autoAlias

Type: Boolean.

When set to false, Vercel for GitHub will not apply the alias upon merge.

{
  "alias": ["example.com"],
  "github": {
    "autoAlias": false
  }
}

github.silent

Type: Boolean.

When set to true, Vercel for GitHub will stop commenting on pull requests and commits.

{
  "github": {
    "silent": true
  }
}

github.autoJobCancelation

Type: Boolean.

When set to false, Vercel for GitHub will always build pushes in sequence without cancelling a build for the most recent commit.

{
  "github": {
    "autoJobCancelation": false
  }
}

Global Configuration

Using the following files and configuration options, you can configure Vercel CLI under your system user.

The two global configuration files are: config.json and auth.json. These files are stored in the com.vercel.cli directory inside XDG_DATA_HOME, which defaults to:

• Linux: ~/.local/share/com.vercel.cli
• macOS: ~/Library/Application Support/com.vercel.cli
• Windows: %APPDATA%\Roaming\xdg.data\com.vercel.cli

config.json

This file is used for global configuration of Vercel deployments. Vercel CLI uses this file as a way to co-ordinate how deployments should be treated, consistently.

The first option is a single _ that gives a description to the file, if a user should find themselves looking through it without context.

The following options are all of the options that can be used by users to configure their Vercel deployments globally on their system for that user profile:

currentTeam

Type: String.

Valid values: A team ID.

This option tells Vercel CLI which context is currently active. If this property exists and contains a team ID, that team is used as the scope for deployments, otherwise if this property does not exist, the user's personal account is used.

{
  "currentTeam": "team_ofwUZockJlL53hINUGCc1ONW"
}

collectMetrics

Type: Boolean.

Valid values: true (default), false.

This option defines whether Vercel CLI should collect anonymous metrics about which commands are invoked the most, how long they take to run, and which errors customers are running into.

{
  "collectMetrics": true
}

auth.json

This file should not be edited manually. It exists to contain the authentication information for the Vercel clients.

In the case that you are uploading your global configuration setup to a potentially insecure destination, we highly recommend ensuring that this file will not be uploaded, as it allows an attacker to gain access to your provider accounts.