Configuration
When using Now CLI, Now for GitHub or Now for GitLab, 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.
The following sections describe each field allowed in a now.json
configuration file and how to use them.
Each deployment receives and understands the now.json
configuration as instructions of how to build and then act when deployed.
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"]
}
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.
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" }
]
}
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 withLocation:
header to implement redirects.continue
: A boolean to change matching behavior. Iftrue
, routing will continue even when thesrc
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.
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 (without authentication with ZEIT).
Usage Example:
{
"public": true
}
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
}
}
Reserved Variables
The following environment variable names are reserved and therefore unavailable for use:
AWS_REGION
AWS_DEFAULT_REGION
AWS_ACCESS_KEY_ID
AWS_SECRET_KEY
AWS_SECRET_ACCESS_KEY
AWS_EXECUTION_ENV
AWS_LAMBDA_LOG_GROUP_NAME
AWS_LAMBDA_LOG_STREAM_NAME
AWS_LAMBDA_FUNCTION_NAME
AWS_LAMBDA_FUNCTION_MEMORY_SIZE
AWS_LAMBDA_FUNCTION_VERSION
AWS_SESSION_TOKEN
NOW_REGION
TZ
_HANDLER
LAMBDA_TASK_ROOT
LAMBDA_RUNTIME_DIR
Using any of these environment variables will result in the deployment failing.
Schemas
If you are looking for a strict or machine-friendly specification of the configuration, we recommend looking at zeit/schemas
.
Global Configuration
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.