Introduction
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:
Category | Description |
---|---|
General configuration options that describe how your project should act with Vercel. | |
Configuration options related to automatic Deployments via Git. | |
Routing configuration for projects with Vercel. | |
Configuration options for usage of Vercel CLI. |
Project
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 (between128
and3008
, in intervals of64
).maxDuration
(optional): An integer defining how long your Serverless Function should be allowed to run on every request in seconds (between1
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.
memory
and maxDuration
can be 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.
functions
property when not using the /api
directory for your Serverless Functions. If this behavior is required, you should use the builds property instead.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:
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 you are using Git, iad1
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
support targeting a region generically, by omitting the number. If sfo
is specified, our backend will select a singular region (like sfo1
) at deploy time.{
"regions": ["iad1", "sfo"]
}
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
.
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.
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
anddestination
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). Whentrue
, the status code is 308. Whenfalse
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
anddestination
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.
source
property should NOT be a file because precendence is given to the filesystem prior to rewrites being applied. Instead, you should rename your static file or Serverless Function.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/:match*", "destination": "https://example.com/:match*" }
]
}
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
, andvalue
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"
}
]
}
]
}
name
name
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: 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
version
property should not be used anymore, as ZEIT Now 1.0 was shut down.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
To assign a custom Domain to your Project, please define it in the Project Settings instead. Once you've defined Domains there, 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.
{
"alias": ["my-domain.com", "my-alias"]
}
scope
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 (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"
}
scope
property because the repository is already connected to a project.env
To add custom Environment Variables to your Project, please define them in the Project Settings instead. Then you will be able to take advantage of the richest feature set.
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
To add custom Environment Variables to your Project, please define them in the Project Settings instead. Then you will be able to take advantage of the richest feature set.
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
To customize Serverless Functions, please use the functions property instead. If you'd like to deploy a monorepo, learn more about how to do it here.
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" }
]
}
builds
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@vercel/static
.routes
routes
property is not recommended.To customize the platform's routing behavior, please use cleanUrls, trailingSlash, redirects, rewrites, and/or headers instead.
It is not possible to use
routes
in combination with any of these properties.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 withLocation:
header to implement redirects.continue
: A boolean to change matching behavior. Iftrue
, routing will continue even when thesrc
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:
Git
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
}
}
Routes
Vercel uses Routes to define the behavior of how a request is handled by the routing layer. For example, you might use a Route to proxy a URL to another, redirect a client, or apply a header with the response to a request.
By default, routing is defined by the filesystem of your deployment. For example, if a user makes a request to /123.png
, and your vercel.json
file does not contain any routes with a valid src
matching that path, it will fallback to the filesystem and serve /123.png
if it exists.
/api
directory to provide filesystem routing and handle dynamic routing with path segments, without the need for configuration.A Route can be defined within a project's vercel.json
configuration file as an object within an array assigned to the routes
property, like the following which creates a simple proxy from one path to another:
{
"routes": [{ "src": "/about", "dest": "/about.html" }]
}
An example vercel.json
file with a routes
property that proxies one path to another upon request.
Vercel Routes have multiple properties for each route object that help define the behavior of a response to each request to a particular path.
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.
dest
path to any URL, Vercel hosted Serverless Function, or even non Vercel hosted URLs as shown in the code above. If you don't perform any proxying, you can safely remove dest
.{
"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.
routes
, these are defined in the same way.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.
Location
property can also point to non Vercel hosted URLs.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.
vercel.json
configuration that tells Vercel to build JavaScript files with Node.js and outputs them as Serverless Functions.Advanced
Cascading Order
Routes are applied in the order they are listed in the routes
array. Take the following configuration; for example:
{
"routes": [
{ "src": "/(.*)", "dest": "/" },
{ "src": "/first-page", "dest": "/first-page.html" }
]
}
An incorrect example vercel.json
file that will match allroutes
and proxy them to /
In the example configuration above, since the first route matches all possible paths, the second route will not be used. The order of these routes would have to switch for the latter route to apply to the /first-page
path.
The correct configuration for all routes to take affect would be the following:
{ "routes": [ { "src": "/first-page", "dest": "/first-page.html" }, { "src": "/(.*)", "dest": "/" } ] }
A correct example vercel.json
file that will match allroutes
, only proxying to /
if there are no matches.
This type of configuration can be seen in single-page applications where custom paths need to route to the index.html
file.
Route Parameters
Using PCRE Named Subpatterns, or capture groups, you can capture part of a path and use it in either the dest
or headers
properties.
Using route parameters enables you to change the format of your URLs easily without needing complicated routing code.
For example, if you are using URL parameters but want to use a custom URL path you can use the following:
{ "routes": [{ "src": "/product/(?<id>[^/]+)", "dest": "/product?id=$id" }] }
Using a URL parameter in src
and proxying it as a custom URL path in dest
.
{ "rewrites": [{ "source": "/product/:id", "destination": "/product" }] }
An equivalent example to the routes
usage above, but instead using rewrites
.
This will take a URL, like /product/532004
and proxies it to /product?id=532004
with the user seeing your custom URL in their browser.
^
, asserting the start of the path string, and $
, asserting the end of the path string, are implied and are not necessary to write.As another example, if you want to redirect from all paths under a certain directory but want to keep the path in the new location, you can use the following:
{ "routes": [ { "src": "/posts/(.*)", "status": 301, "headers": { "Location": "/blog/$1" } } ] }
Redirecting from all paths in the posts
directory but keeping the path in the new location.
{ "redirects": [ { "source": "/posts/(.*)", "destination": "/blog/$1", "statusCode": 301 } ] }
An equivalent example to the routes
usage above, but instead using redirects
.
If you are using a Next.js app and want to learn more about using custom routes with Vercel, read our guide:
Wildcard Routes
Sometimes, you will have wildcard routes that overlap with other routes. For example:
{
"routes": [
{ "src": "/about" },
{ "src": "/contact" },
{ "src": "/([^/]+)", "dest": "/blog?slug=$1" }
]
}
A vercel.json
file where filesystem routes are explicitly defined.
You might find that there are many routes without a dest
. These routes can be handled without being explicitly defined by using handle filesystem. Handle filesystem works the same as if you hardcoded all the routes in its place.
{
"routes": [
{ "handle": "filesystem" },
{ "src": "/([^/]+)", "dest": "/blog?slug=$1" }
]
}
A vercel.json
file, using handle filesystem to route to filesystem routes.
In this example, handle filesystem expands to route /about
and /contact
.
When using rewrites
, handle filesystem is assumed so this example can be simplified to the following:
{ "rewrites": [{ "source": "/:slug", "destination": "/blog" }] }
An equivalent example to the routes
example above, but instead using rewrites
.
Custom 404
If you wish to create a custom 404 page, you should follow your framework's documentation.
- Next.js: Customizing the 404 Page
- Gatsby: Adding a 404 page
- Hugo: Custom 404 Page
- Jekyll: Custom 404 Page
- Eleventy: Adding a 404 Not Found Page
If you need to assign a different file, you can use routes
.
{ "routes": [ { "handle": "filesystem" }, { "src": "/(.*)", "status": 404, "dest": "/other-404.html" } ] }
A vercel.json
file, assigning other-404.html
as the 404 page for any path not matched in the filesystem.
In the snippet above, precedence is given to the filesystem, routing only to /other-404.html
when no other file matches the requested path.
In some rare cases, you may wish to set the status code to 404 regardless of the file's existence on the filesystem.
{ "routes": [{ "src": "/stats", "status": 404, "dest": "/custom.html" }] }
A vercel.json
file, setting a 404
status code for the /stats
path.
In the snippet above, visiting the /stats
path will respond with a 404
status code.
SPA Fallback
A common pattern with single-page applications (SPAs) is to route everything towards a single file with the application parsing the path to handle the routing itself. Most SPAs have assets to serve as well, so you should handle the filesystem before rewriting the path:
{ "version": 2, "routes": [ { "handle": "filesystem" }, { "src": "/.*", "dest": "/index.html" } ] }
A vercel.json
file, providing a fallback to index.html
after checking for matches against filesystem routes.
{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }
An equivalent example to the routes
example above, but instead using rewrites
.
In the example above, routing will take place based on the filesystem first, allowing for correct routing of assets and Serverless Functions, before falling back to the index.html
file.
Intercepting Routes
Routes can be intercepted by placing them either before or after "handle": "filesystem"
, this can be used to change the behavior of how your routes work.
For example, say the directory structure of a user's project looks like this:
project/ about.html contact.html blog.js index.html
An example project directory structure.
If you want to create a route that does not interfere with the other files in the filesystem, you should add "handle": "filesystem"
before:
{ "version": 2, "routes": [ { "handle": "filesystem" }, { "src": "/(?<slug>[^/]+)", "dest": "/blog?slug=$slug" } ] }
A vercel.json
file, providing a /blog
route after checking for matches against filesystem routes.
This is the equivalent of writing the routes below except when you add a new file, you don't need to change any config:
{ "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" } ] }
A vercel.json
file, expanded to show the effect of using the filesystem to handle routing.
If you want to append headers to block some of those paths, you need a route that comes before "handle": "filesystem"
:
{ "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" } ] }
A vercel.json
file that will continue matching routes after /about.html
is matched.
By using "continue": true
, routes will continue to be matched, rather than stopping at the first match.
Using continue
There are some cases where you might want to continue routing after making a match. This is useful when scoping URLs or appending headers.
Global Headers with continue
A common usage for "continue": true
is to add global headers to routes, this is shown in the example:
{ "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" } ] }
A vercel.json
file using continue
to add global headers.
{ "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" }] }
An equivalent example to the routes
example above, but instead using headers
and rewrites
.
In this example, /test
would be cached for 3600
, /blog/whatever
would be cached for 600
. It's important to note when using continue
and headers, if a header is already set, it is overridden.
dest and continue
When you need to rewrite the URL without matching, you should use "continue": true
.
{ "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" } ] }
A vercel.json
file using continue
to rewrite a URL without matching.
{ "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" } ] }
An equivalent example to the routes
example above, but instead using headers
and rewrites
.
In this example, when requesting /test
, it will look for a response at /src/public/test
. Any routes that follow the dest
+ continue
route will match against the new path. For example, /test
would match all 3 routes.
Common Regex
When using the .
character in a PCRE Regex, you should keep in mind that in regex, it matches anything. A literal .
must be escaped with two backslashes \\\\.
. Forward slashes do not need to be escaped because the regular expression is enclosed in quotes.
Incorrect:
{ "src": "\\/test\\/file.json", "status": 404, "dest": "/404" }
An incorrect example of a vercel.json
route.
Considering this example, /test/file.json
would match, but /test/file-json
would too. This is not intended. The \\/
slashes are distracting and needless.
Correct:
{ "src": "/test/file\\\\.json", "status": 404, "dest": "/404" }
A correct example of a vercel.json
route.
When using rewrites
, the .
character is considered a literal unless wrapped in a group.
{ "rewrites": [ { "source": "/test/file.json", "destination": "/api/generate-json" }, { "source": "/proxy/(.*)", "destination": "https://example.com/$1" } ] }
The first rewrite generates a json
file from a Serverless Function. The second rewrite proxies all traffic to example.com
.
Catch-All Except
A common pattern for URL slugs is catch-all except:
{ "src": "/blog/([^/]+)", "dest": "/blog?post=$1" }
A vercel.json
route using a catch-all except regex.
{ "rewrites": [{ "source": "/blog/:post", "destination": "/blog" }] }
An equivalent example to the routes
example above, but instead using rewrites
.
Anything that is not a /
will match in $1
. This allows /blog/post
to work, while not allowing /blog/post/edit
.
Negative Lookahead
When using catch-alls, it might make sense to exclude certain patterns instead of just a character. A negative lookahead might be useful with a directory structure similar to this:
project/ blog/ index.html post.html www/ index.html about.html
An example project directory structure.
In order to make /
use www/index.html
, you have to create a route:
{ "version": 2, "routes": [{ "src": "/(?!blog/?)(.*)", "dest": "/www/$1", "continue": true }] }
A vercel.json
route using a negative lookahead.
(?!blog/?)
is a negative lookahead and ensures the route doesn't start with /blog/
.
Limits
There is a limit of 256 route objects within a routes
array. If there are more than this limit, the deployment will fail.
Global
Using the following files and configuration options, you can configure Vercel CLI under your system user.
There are two global configuration files; config.json
and auth.json
. By default, these files are held in a directory named .vercel
within the user's home directory. For example on Unix based systems they will be found at ~/.vercel/*.json
.
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"
}
api
Type: String
.
Valid values: An API Origin URL.
This option selects which API Origin Vercel CLI should use when performing an action requiring the API.
{
"api": "https://api-sfo1.zeit.co"
}
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.