Introduction

Configuration Reference

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

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

Configuration options for the following are described on this page:

Category
Description
General configuration options that describe how your project should act with ZEIT Now.
Conigurations options related to ZEIT Now Git integrations.
Routing configuration for projects with ZEIT Now.
Configuration options for usage of Now CLI.

Project

name

Type: String.

Valid values: string name for the deployment.

Limit: A maximum length of 52 characters

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.

Usage Example:

{
  "name": "zeit-chat"
}

version

Type: Number.

Valid values: 1, 2.

Specifies the Now 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).

Usage Example:

{
  "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 .now.sh or a Custom Deployment Suffix.

Limit: A maximum of 64 aliases in the array

The alias or aliases are applied automatically using Now for GitHub or Now for GitLab when merging or pushing to the default branch.

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

Usage Example:

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

Note: Aliases from a now.json file will be ignored when there are domains that have been configured for the project through the dashboard.

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 Now CLI.

Furthermore, it also affects any other actions that the user takes within the directory that contains this configuration (e.g. listing secrets using now secrets ls).

Usage Example:

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

Usage Example:

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.

Usage Example:

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): A 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.

Usage Example:

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": "@now/static" },
    { "src": "*.py", "use": "@now/python" },
    { "src": "*.js", "use": "@now/node" }
  ]
}

Note: When at least one 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 white-list static files explicitly with@now/static.

For more information on Builds and Builders, 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.

Usage Example:

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

{
  "builds": [
    { "src": "*.html", "use": "@now/static" },
    { "src": "*.js", "use": "@now/node" }
  ],
  "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": 301, "headers": { "Location": "https://zeit.co/" } }
  ]
}

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

Note: The values in 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.

Usage Example:

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

public

Type: Boolean.

When set to true, both the source view and logs view will be publicly accessible (when the user is authenticated with ZEIT).

Usage Example:

{
  "public": true
}

Git Integrations

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

github.enabled

Type: Boolean.

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

Usage Example:

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

github.autoAlias

Type: Boolean.

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

Usage Example:

{
  "alias": ["my-zeit-website.com"],
  "github": {
    "autoAlias": false
  }
}

github.silent

Type: Boolean.

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

Usage Example:

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

github.autoJobCancelation

Type: Boolean.

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

Usage Example:

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

Routes

ZEIT Now 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 now.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.

Note: For Serverless Function routes, you can configure an /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 now.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 now.json file with a routes property that proxies one path to another upon request.

ZEIT Now 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 now.json configuration that takes a src path and proxies it to a destination dest path.

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

An example now.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 Now 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 now.json file with routes properties that proxy paths to another upon request.

Note: You can point the dest path to any URL, Now hosted Serverless Function, or even non-Now 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.

Note: You can also add custom headers to your 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 Now 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 301 (Moved Permanently).

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

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

Note: In a redirect case as shown above, the Location property can also point to non-Now hosted URLs.

Read more about redirecting your www. subdomain to your root domain:

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"
    }
  ],
  "builds": [{ "src": "*.js", "use": "@now/node" }]
}

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

Note: The above example uses the @now/node Builder as an example of a now.json configuration that tells Now 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 now.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 now.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

Note: This method is for advanced usecases when using route parameters and path segments. For most cases, please see the Serverless Functions documentation on path segments for the recommended method, using the filesystem.

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.

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.

Note: Both ^, 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.

If you are using a Next.js app and want to learn more about using custom routes with ZEIT Now, 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 now.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 now.json file, using handle filesystem to route to filesystem routes.

In this example, handle filesystem expands to route /about and /contact.

Custom 404

The routes array is processed before attempting a match. For example, this allows you to send a 404 status code for specific route patterns:

{
  "version": 2,
  "routes": [{ "src": "/build/stats", "status": 404, "dest": "/404" }]
}

A now.json file, setting a 404 status code for the /build/stats route.

This would return a 404 status code for the /build/stats route.

To provide a custom 404 route, you can rely on the filesystem, providing a custom error page if there are no matches. The code below shows an example of how to do this:

{
  "version": 2,
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "status": 404, "dest": "/404" }
  ]
}

A now.json file, setting a 404 status code for any routes not matched in the filesystem.

In the snippet above, precedence is given to the filesystem, routing only to /404 if there is no match.

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 now.json file, providing a fallback to index.html after checking for matches against filesystem routes.

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 now.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 now.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 now.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 now.json file using continue to add global headers.

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 now.json file using continue to rewrite a URL without matching.

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 . is denoted \.. 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 now.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 now.json route.

Catch-All Except

A common pattern for URL slugs is catch-all except:

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

A now.json route using a catch-all except regex.

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 now.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 Now 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 .now within the user's home directory. For example on Unix based systems they will be found at ~/.now/*.json.

config.json

This file is used for global configuration of ZEIT Now deployments. Now 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 Now deployments globally on their system for that user profile:

currentTeam

Type: String.

Valid values: A team ID.

This option tells Now 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 Now 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 Now 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 ZEIT Now 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.