Netlify Config

This library loads, validates, and normalizes the Netlify configuration.

Netlify can be configured:

• In the build settings.
• In a netlify.toml file in the repository root directory or site base directory.

Install

npm install @netlify/config

Usage (Node.js)

getNetlifyConfig(options?)

options: object?
Return value: Promise<object>

const getNetlifyConfig = require('@netlify/config')

const exampleFunction = async function () {
  const { config, configPath, buildDir, context, branch, token, siteInfo } = await getNetlifyConfig(options)
  // {
  // "config": {
  //     "build": {
  //       "command": "gulp build",
  //       "commandOrigin": "config",
  //       "environment": {
  //         "NETLIFY_BUILD_DEBUG": "true",
  //         "NODE_VERSION": "12",
  //         "AWS_LAMBDA_JS_RUNTIME": "nodejs10.x"
  //       },
  //       "functions": "/home/me/cv-website/functions",
  //       "edge_handlers": "/home/me/cv-website/edge-handlers",
  //       "publish": "/home/me/cv-website/build",
  //       "processing": {
  //         "css": {
  //           "bundle": true,
  //           "minify": true
  //         },
  //         "js": {
  //           "bundle": true,
  //           "minify": true
  //         },
  //         "html": {
  //           "pretty_urls": true
  //         },
  //         "images": {
  //           "compress": true
  //         }
  //       }
  //     },
  //     "plugins": [
  //       {
  //         "package": "@netlify/plugin-sitemap",
  //         "inputs": {},
  //         "origin": "config"
  //       }
  //     ]
  // },
  // "configPath": "/home/me/cv-website/netlify.toml",
  // "buildDir": "/home/me/cv-website",
  // "context": "production",
  // "branch": "master",
  // "siteInfo": {
  //     "id": "418b94bc-93cd-411a-937a-ae4c734f17c4",
  //     "name": "mick",
  //     "build_settings": {
  //       "cmd": "",
  //       "dir": "",
  //       "env": { ... },
  //       "functions_dir": "",
  //       "base": "",
  //     },
  //     ...
  // },
  // "env": {
  //   "general": {
  //     "CONTEXT": "production",
  //     ...
  //   },
  //   "accounts": { ... },
  //   "addons": { ... },
  //   "ui": { ... },
  //   "configFile": { ... },
  //   "all": { ... },
  // }
  // "token": "564194bc-12cd-511a-037a-be4c734f17c4"
  // }
}

Options

The options are an optional object with the following properties.

Those options are automatically set when using @netlify/config in the Netlify production CI or with Netlify CLI.

debug

Type: boolean
Default value: false unless the NETLIFY_BUILD_DEBUG environment variable is set.

Prints debugging information showing the configuration being resolved.

offline

Type: boolean
Default value: false

Do not send requests to the Netlify API to retrieve site settings.

buffer

Type: boolean
Default value: false

When using debug, returns the logs instead of printing them on the console.

config

Type: string

Path to the netlify.toml. It is either an absolute path or a path relative to the cwd.

If not specified, it is searched in the following directories (by highest priority order):

• base directory
• repositoryRoot
• current directory
• any parent directory

Otherwise, no netlify.toml is used.

repositoryRoot

Type: string
Default value: see cwd

Repository root directory. This is used in the following cases:

• Searching for the netlify.toml (see config)
• When a base directory was specified, its path is relative to the repository root directory
• The functions, edge_handlers and publish directories are relative to the repository root directory or (if specified) the base directory
• Determining the build directory

If not specified, it is automatically guessed by looking for any .git directory from the cwd, and up. If none is found, the cwd is used instead.

cwd

Type: string
Default value: process.cwd()

Current directory. This is used in the following cases:

• Searching for the netlify.toml (see config)
• Searching for the repositoryRoot
• In a monorepo, when stepping inside a specific package in the console, that package is automatically used as base directory

context

Type: string
Default value: environment variable CONTEXT, or "production"

Deploy context.

The netlify.toml can contain contexts.{CONTEXT} properties, which are like build properties but only applied when {CONTEXT} matches.

branch

Type: string
Default value: environment variable BRANCH, current git branch, or "master"

Same as context but using a git branch name.

token

Type: string
Default value: environment variable NETLIFY_AUTH_TOKEN

Netlify API token.

This is used to retrieve siteInfo.

siteId

Type: string
Default value: environment variable NETLIFY_SITE_ID

Netlify Site ID.

This is used to retrieve siteInfo.

env

Type: object

Environment variable to use, in addition to the current process.env. This is used as the default values of other options.

mode

Type: string
Default value: "require"

What is calling @netlify/config. Can be:

• "buildbot": Netlify production CI
• "cli": Netlify CLI
• "require": anything else

This is used for the following cases:

• if mode is buildbot, the siteInfo is not retrieved because it is also passed using another internal option.

defaultConfig

Type: string

Configuration object used as default. This is an object serialized with JSON.

inlineConfig

Type: object

Configuration object overriding any properties. This is a JavaScript object.

Return value

The return value is a Promise resolving to an object with the following properties.

config

Type: object

Resolved configuration object.

configPath

Type: string?

Absolute path to the netlify.toml, if any.

buildDir

Type: string

Absolute path to the build directory.

The build directory is the current directory in which most build operations, including the build command, execute. It is usually either the repositoryRoot or (if specified) the base directory.

context

Type: string

Resolved context. See the context option.

branch

Type: string

Resolved git branch. See the branch option.

siteInfo

Type: string?

Netlify Site information retrieved using the getSite Netlify API endpoint. This is used to retrieve Build settings set in the Netlify App: plugins, Build command, Publish directory, Functions directory, Base directory, Environment variables.

This might not be available depending on the options passed.

token

Type: string

Netlify API token. This takes into account the token option but also some Netlify-specific environment variables.

api

Type: NetlifyClient?

Netlify JavaScript client instance used to retrieve the siteInfo.

logs

Type: object?

When the buffer option is used, this contains two arrays stdout and stderr with the logs.

env

Type: object?

Site's environment variables. Each property is an object of key-value pairs:

• general: general environment variables set for all sites
• account: environment variables set in the Netlify UI for a specific account
• addons: addon-specific environment variables
• ui: environment variables set in the Netlify UI for a specific site
• configFile: environment variables set in netlify.toml
• all: all of the above, merged

Usage (CLI)

$ netlify-config

Like getNetlifyConfig(), but in the CLI. The return value is printed on stdout.

The CLI flags use the same options.