@netlify/config

    15.7.4 • Public • Published

    Netlify Config

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

    Netlify can be configured:

    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)
      // {
      // "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 getNetlifyConfig(), but in the CLI. The return value is printed on stdout.

    The CLI flags use the same options.

    Install

    npm i @netlify/config

    DownloadsWeekly Downloads

    79,355

    Version

    15.7.4

    License

    MIT

    Unpacked Size

    119 kB

    Total Files

    57

    Last publish

    Collaborators

    • jgee0110
    • biilmann
    • benaiah
    • shortdiv
    • marcus.netlify
    • ehmicky
    • erezro
    • lesliecdubs
    • neolegends
    • lindsaylevine
    • jgantunes
    • eduardoboucas
    • charliegerard
    • netlify-bot
    • nasiba
    • zachleat
    • ascorbic