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)

resolveConfig(options?)

options: object?
Return value: Promise<object>

import { resolveConfig } from '@netlify/config'

const exampleFunction = async function () {
  const { config, configPath, buildDir, context, branch, token, siteInfo } = await resolveConfig(options)
  // {
  // "siteInfo": {
  //   "id": "418b94bc-93cd-411a-937a-ae4c734f17c4",
  //   "name": "mick",
  //   "build_settings": {
  //     "cmd": "",
  //     "dir": "",
  //     "env": { ... },
  //     "functions_dir": "",
  //     "base": "",
  //   },
  //   ...
  // },
  // "accounts": [
  //   {
  //     "name": "my team",
  //     "slug": "me",
  //     ...
  //   },
  //   ...
  // ],
  // "addons": [],
  // "env": {
  //   "NODE_VERSION": { "sources": ["configFile"], "value": "16" },
  //   ...
  // },
  // "configPath": "/home/me/code/cv-website/netlify.toml",
  // "buildDir": "/home/me/code/cv-website",
  // "repositoryRoot": "/home/me/code/cv-website",
  // "config": {
  //   "functionsDirectory": "/home/me/code/cv-website/netlify/functions",
  //   "functionsDirectoryOrigin": "default",
  //   "functions": { "*": { "node_bundler": "esbuild" } },
  //   "plugins": [
  //     {
  //       "package": "@netlify/plugin-sitemap",
  //       "inputs": {},
  //       "origin": "config"
  //     }
  //   ],
  //   "build": {
  //     "publish": "/home/me/code/cv-website/build",
  //     "publishOrigin": "default",
  //     "command": "gulp build",
  //     "commandOrigin": "config",
  //     "functions": "/home/me/code/cv-website/netlify/functions"
  //   }
  // },
  // "context": "production",
  // "branch": "main",
  // "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, "main" 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.

host

Type: string
Default value: api.netlify.com

Host of the Netlify API.

scheme

Type: string
Default value: https

Scheme/protocol of the Netlify API.

pathPrefix

Type: string
Default value: /api/v1

Base path prefix of the Netlify API.

siteId

Type: string
Default value: environment variable NETLIFY_SITE_ID

Netlify Site ID.

This is used to retrieve siteInfo, accounts and addons.

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, siteInfo, accounts and addons are not retrieved because they are 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.

configMutations

Type: array

Array of changes to apply to the configuration. Each change must be an object with three properties:

• keys: array of keys targetting the property to change
• value: new value of that property
• event: build event when this change was applied, e.g. onPreBuild

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 this file exists.

headersPath

Type: string

Absolute path to the _headers, even if this file does not exist.

redirectsPath

Type: string

Absolute path to the _redirects, even if this file does not exist.

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.

repositoryRoot

Type: string

The computed value of repositoryRoot.

context

Type: string

Resolved context. See the context option.

branch

Type: string

Resolved git branch. See the branch option.

siteInfo

Type: object

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 be empty depending on the options passed.

accounts

Type: object[]

Netlify accounts retrieved using the listAccountsForUser Netlify API endpoint. This is used to retrieve account-level environment variables.

This might be empty depending on the options passed.

addons

Type: object[]

Netlify addons retrieved using the listServiceInstancesForSite Netlify API endpoint. This is used to retrieve addon-specific environment variables.

This might be empty 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 siteInfo, accounts and addons.

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 environment variable value is an object with the following properties:

• value string
• sources string[] among:
  • 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

Usage (CLI)

$ netlify-config

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

The CLI flags use the same options.