Configuration Reference

This page is a reference to the different ways of configuring your Vercel projects and Vercel CLI.

Using a vercel.json configuration file, placed at the root of a project, you can provide a list of options that changes the default behavior of the Vercel platform.

Configuration options for the following are described on this page:

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. The 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 Vercel Platform version the deployment should use and is known to work with. We strongly recommend setting a version when working on production systems or using source control (e.g. Git).

{
  "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 (user 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 static env to all Builds andSECRET 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" }
  ]
}

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 (like api/*.js or api/test.js).

Value definition:

• runtime (optional): The npm package name of a Runtime, including its version.
• memory (optional): An integer defining the memory your Serverless Function should be provided with (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.
• 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.

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.

When deployed, each Serverless Function receives the following properties:

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

To configure them, you can add the functions property like so:

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

Both sub properties are optional and need to match the following constraints mentioned at the top of this section.

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:

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.

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

{
  "routes": [
    { "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": "/.*", "dest": "https://my-old-site.com"},
    { "src": "/legacy", "status": 404},
    { "src": "/redirect", "status": 308, "headers": { "Location": "https://example.com/" } }
  ]
}

For more information on routes, see the documentation:

regions

Type: Array of region identifier String.

Valid values: a list of valid region identifiers.

By setting and modifying this value, you can decide the deployment regions of the Serverless Functions that get created as a result of the build steps. By default, the closest region to the geographical location of the deployment is used, or if using a Vercel for Git Integration, SFO is used by default.

This value does not impact static files or edge caches, since deployments always have a CDN layer in front.

The special value all can be used to target all available regions.

{
  "regions": ["sfo1", "bru"]
}

public

Type: Boolean.

Default Value: false.

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

{
  "public": true
}

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
}

trailingSlash

Type: Boolean.

Default Value: undefined.

{
  "trailingSlash": false
}

{
  "trailingSlash": true
}

redirects

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.

This example configures custom redirects that map to static files, Serverless Functions, and external URLs.

{
  "redirects": [
    { "source": "/me", "destination": "/profile.html" },
    { "source": "/user", "destination": "/api/user", "permanent": false },
    { "source": "/view-source", "destination": "https://github.com/vercel/vercel" }
  ]
}

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.

rewrites

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.

This example configures custom rewrites that map to static files, Serverless Functions, automatic query string matching, and a wildcard proxy.

{
  "rewrites": [
    { "source": "/about", "destination": "/about-our-company.html" },
    { "source": "/resize/:width/:height", "destination": "/api/sharp" },
    { "source": "/user/:id", "destination": "/api/user" },
    { "source": "/proxy/(.*)", "destination": "https://example.com/$1" }
  ]
}

headers

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 array of key/value pairs representing each response header.

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": "/api/feed",
      "headers" : [
        {
          "key" : "Content-Type",
          "value" : "application/rss+xml"
        },
        {
          "key" : "Cache-Control",
          "value" : "public, max-age=3600"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers" : [
        {
          "key" : "X-Content-Type-Options",
          "value" : "nosniff"
        },
        {
          "key" : "X-Frame-Options",
          "value" : "DENY"
        },
        {
          "key" : "X-XSS-Protection",
          "value" : "1; mode=block"
        }
      ]
    }
  ]
}

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
  }
}

src

Type: String supporting PCRE Regex and Route Parameters like /product/(?<id>[^/]+).

For each route, src is required to set the path which the behavior will affect.

The following example shows a vercel.json configuration that takes a src path and proxies it to a destination dest path.

{
  "routes": [{ "src": "/about", "dest": "/about.html" }]
}

An example vercel.json file with a routes property that proxies one path to another upon request.

dest

Type: String

dest is used to proxy the src path to another path, such as another URL or Vercel hosted Serverless Function.

The example for the src property shows how both methods work together to create a proxy.

{
  "routes": [
    { "src": "/about", "dest": "https://about.me" },
    { "src": "/action", "dest": "my-serverless-function-action/index" }
  ]
}

An example vercel.json file with routes properties that proxy paths to another upon request.

{
  "routes": [{ "src": "/about" }]
}

This will route to /about without proxying, but routes like this are usually redundant with handle filesystem.

headers

Type: Object

The headers property is an object supporting HTTP headers as the keys, with the intended value as the key's value.

An example of using the headers property to add shared caching headers to all files in an images directory:

{
  "routes": [
    {
      "src": "/images/(.*)",
      "headers": { "cache-control": "s-maxage=604800" },
      "dest": "/images/$1"
    }
  ]
}

Setting cache-control headers for all paths under an images directory with routes.

continue

Type: Boolean

The continue property allows routing to continue even though the src was matched.

For example, you can use this property in combination with the headers property to append headers to a broader group of routes instead of applying it to every route.

{
  "routes": [
    {
      "src": "/blog.*",
      "headers": { "Cache-Control": "max-age=3600" },
      "continue": true
    },
    {
      "src": "/blog/([^/]+)",
      "dest": "/blog?slug=$1"
    }
  ]
}

In this case, the Cache-Control header will be applied to any route starting with /blog.

status

Type: Integer

The status property defines the status code that Vercel should respond with when a path is requested.

For example, you can use this property in combination with the headers property to create a redirect with the initial status code of 308 (Moved Permanently).

{
  "routes": [
    {
      "src": "/about.html",
      "status": 308,
      "headers": { "Location": "/about-us.html" }
    }
  ]
}

Redirecting one path to another using the status property to provide a HTTP status code.

Read more about redirecting your www. subdomain to your root domain in the custom domains documentation.

methods

Type: Array

The methods property can be used to define what HTTP request methods a particular path accepts.

The value of this property can be any HTTP request method, with the default being that the path can accept any method.

As an example, you can use this property when you have an API endpoint and only want to allow GET or POST request methods:

{
  "routes": [
    {
      "src": "/api/user.js",
      "methods": ["POST", "GET"],
      "dest": "/api/user.js"
    }
  ]
}

Accepting only POST and GET HTTP request methods on an API endpoint.

Advanced

{
  "routes": [
    { "src": "/(.*)", "dest": "/" },
    { "src": "/first-page", "dest": "/first-page.html" }
  ]
}

{
  "routes": [
    { "src": "/first-page", "dest": "/first-page.html" },
    { "src": "/(.*)", "dest": "/" }
  ]
}

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

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

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

{
  "redirects": [
    {
      "source": "/posts/(.*)",
      "destination": "/blog/$1",
      "statusCode": 301
    }
  ]
}

{
  "routes": [
    { "src": "/about" },
    { "src": "/contact" },
    { "src": "/([^/]+)", "dest": "/blog?slug=$1" }
  ]
}

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/([^/]+)", "dest": "/blog?slug=$1" }
  ]
}

{
  "rewrites": [{ "source": "/:slug", "destination": "/blog" }]
}

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "status": 404, "dest": "/other-404.html" }
  ]
}

{
  "routes": [{ "src": "/stats", "status": 404, "dest": "/custom.html" }]
}

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

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

project/
  about.html
  contact.html
  blog.js
  index.html

{
  "version": 2,
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(?<slug>[^/]+)", "dest": "/blog?slug=$slug" }
  ]
}

{
  "version": 2,
  "routes": [
    { "src": "/about.html", "dest": "/about.html" },
    { "src": "/index.html", "dest": "/index.html" },
    { "src": "/contact.html", "dest": "/contact.html" },
    { "src": "/secret.html", "dest": "/secret.html" },
    { "src": "/(?<slug>[^/]+)", "dest": "/blog?slug=$slug" }
  ]
}

{
  "version": 2,
  "routes": [
    {
      "src": "/about.html",
      "headers": { "Cache-Control": "max-age=600" },
      "continue": true
    },
    { "src": "/secret.html", "status": 404, "dest": "/404" },
    { "handle": "filesystem" },
    { "src": "/(?<slug>[^/]+)", "dest": "/blog?slug=$slug" }
  ]
}

{
  "version": 2,
  "routes": [
    {
      "src": "/.*",
      "headers": { "Cache-Control": "max-age=3600" },
      "continue": true
    },
    {
      "src": "/blog.*",
      "headers": { "Cache-Control": "max-age=600" },
      "continue": true
    },
    { "src": "/blog/([^/]+)", "dest": "/post?slug=$1" }
  ]
}

{
  "headers": [
    {
      "source": "/.*",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=3600"
        }
      ]
    },
    {
      "source": "/blog.*",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=600"
        }
      ]
    }
  ],
  "rewrites": [{ "source": "/blog/:slug", "destination": "/post" }]
}

{
  "version": 2,
  "routes": [
    {
      "src": "/test",
      "headers": { "Cache-Control": "max-age: 600" },
      "continue": true
    },
    { "src": "/(.*)", "dest": "/src/public/$1", "continue": true },
    { "src": "/src/public/test", "dest": "/src/function/test" }
  ]
}

{
  "headers": [
    {
      "source": "/test",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=600"
        }
      ]
    }
  ],
  "rewrites": [
    { "source": "/(.*)", "destination": "/src/public/$1" },
    { "source": "/src/public/test", "destination": "/src/function/test" }
  ]
}

{ "src": "\/test\/file.json", "status": 404, "dest": "/404" }

{ "src": "/test/file\\.json", "status": 404, "dest": "/404" }

{
  "rewrites": [
    { "source": "/test/file.json", "destination": "/api/generate-json" },
    { "source": "/proxy/(.*)", "destination": "https://example.com/$1" }
  ]
}

{ "src": "/blog/([^/]+)", "dest": "/blog?post=$1" }

{
  "rewrites": [{ "source": "/blog/:post", "destination": "/blog" }]
}

project/
  blog/
    index.html
    post.html
  www/
    index.html
    about.html

{
  "version": 2,
  "routes": [{ "src": "/(?!blog/?)(.*)", "dest": "/www/$1", "continue": true }]
}

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": "team_ofwUZockJlL53hINUGCc1ONW"
}

{
  "api": "https://api-sfo1.zeit.co"
}

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