Deployment Configuration (now.json)

When using Now CLI, Now Desktop or Now for GitHub, the configuration for your deployment is read from the now.json file.

The parameters stored in that file are passed to the Deployment Creation API endpoint, which performs validation and stores the metadata in our backend.

If you are looking for a strict or machine-friendly specification of the configuration, we recommend looking at zeit/schemas.

The following sections describe each field allowed in a now.json configuration file and how to use them.

Each deployment recieves and understands the now.json configuration as instructions of how to build and then act when deployed.

Type: String.

Valid values: string name for the deployment.

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.

Usage Example:
{
  "name": "zeit-chat"
}

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
}

Type: Array or String.

Valid values: domain names (optionally including subdomains) added to the account.

The alias or aliases are applied when merging a PR to the master branch with Now for GitHub, or when deploying to master.

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

Type: Object of String keys and values.

Valid values: environment keys and values.

Environment variables passed to the invoked Lambdas.

Usage Example:
This example will pass the `MY_KEY` static env to all Lambdas and `SECRET` resolved from the `my-secret-name` secret dynamically.
{
  "env": {
    "MY_KEY": "this is the value",
    "SECRET": "@my-secret-name"
  }
}

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 and `SECRET` resolved from the `my-secret-name` secret dynamically.
{
  "build": {
    "env": {
      "MY_KEY": "this is the value",
      "SECRET": "@my-secret-name"
    }
  }
}

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 PHP files and JS files into Lambdas.
{
  "builds": [
    { "src": "*.html", "use": "@now/static" },
    { "src": "*.php", "use": "@now/php" },
    { "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, refer to Builds and Builder documentation.

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.

Example:

The following example configures custom routes that map to static files and lambdas

Usage Example:
This example configures custom routes that map to static files and Lambdas.
{
  "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/" } }
  ]
}

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 Lambdas that get created as a result of the build steps.

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

Type: Boolean.

When set to true, both the source view and logs view will be publically accessible (without authentication with ZEIT).

Usage Example:
{
  "public": true
}

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

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

Type: Boolean.

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

Usage Example:
{
  "github": {
    "silent": true
  }
}

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