@netlify/config
Advanced tools
@netlify/config is a package that helps you programmatically access and manipulate Netlify configuration settings. It allows you to read, validate, and modify the configuration settings for a Netlify site, making it easier to manage and automate deployment settings.
Load Netlify Configuration
This feature allows you to load the Netlify configuration for a site. The `loadConfig` function reads the configuration file and returns the configuration object, which you can then manipulate or inspect.
const { loadConfig } = require('@netlify/config');
(async () => {
const { config } = await loadConfig();
console.log(config);
})();Validate Netlify Configuration
This feature allows you to validate the Netlify configuration. The `validateConfig` function checks the configuration object for any errors or inconsistencies, ensuring that the configuration is correct before deployment.
const { validateConfig } = require('@netlify/config');
(async () => {
const { config } = await loadConfig();
const validationResult = validateConfig(config);
console.log(validationResult);
})();Modify Netlify Configuration
This feature allows you to modify the Netlify configuration. You can load the configuration, make changes to it, and then save the updated configuration back to the file.
const { loadConfig, saveConfig } = require('@netlify/config');
(async () => {
const { config } = await loadConfig();
config.build.command = 'npm run build';
await saveConfig(config);
console.log('Configuration updated');
})();The 'config' package is a popular configuration management tool for Node.js applications. It allows you to define configuration settings for different environments and access them programmatically. Unlike @netlify/config, which is specific to Netlify, 'config' is a general-purpose tool that can be used in any Node.js application.
The 'dotenv' package loads environment variables from a .env file into process.env. It is commonly used to manage configuration settings in Node.js applications. While 'dotenv' is more focused on environment variables, @netlify/config provides a more comprehensive solution for managing Netlify-specific configuration settings.
The 'rc' package is a simple configuration loader for Node.js that supports configuration files, environment variables, and command-line arguments. It is more lightweight compared to @netlify/config and is suitable for applications that need a flexible and straightforward configuration management solution.
This library loads, validates, and normalizes the Netlify configuration.
Netlify can be configured:
netlify.toml file in the repository root
directory or site base directory.npm install @netlify/config
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"
// }
}
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.
Type: boolean
Default value: false unless the NETLIFY_BUILD_DEBUG environment variable is set.
Prints debugging information showing the configuration being resolved.
Type: boolean
Default value: false
Do not send requests to the Netlify API to retrieve site settings.
Type: boolean
Default value: false
When using debug, returns the logs instead of printing them on the console.
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 directoryrepositoryRootOtherwise, no netlify.toml is used.
Type: string
Default value: see cwd
Repository root directory. This is used in the following cases:
netlify.toml (see config)base directory was specified, its path is relative to the repository root directoryfunctions, edge_handlers and publish directories are relative to the repository root directory or (if
specified) the base directoryIf 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.
Type: string
Default value: process.cwd()
Current directory. This is used in the following cases:
netlify.toml (see config)repositoryRootbase
directoryType: string
Default value: environment variable CONTEXT, or "production"
The netlify.toml can contain contexts.{CONTEXT} properties, which are like build properties but only applied when
{CONTEXT} matches.
Type: string
Default value: environment variable BRANCH, current git branch, "main" or "master".
Same as context but using a git branch name.
Type: string
Default value: environment variable NETLIFY_AUTH_TOKEN
Netlify API token.
This is used to retrieve siteInfo.
Type: string
Default value: api.netlify.com
Host of the Netlify API.
Type: string
Default value: https
Scheme/protocol of the Netlify API.
Type: string
Default value: /api/v1
Base path prefix of the Netlify API.
Type: string
Default value: environment variable NETLIFY_SITE_ID
Netlify Site ID.
This is used to retrieve siteInfo, accounts and addons.
Type: object
Environment variable to use, in addition to the current process.env. This is used as the default values of other
options.
Type: string
Default value: "require"
What is calling @netlify/config. Can be:
"buildbot": Netlify production CI"cli": Netlify CLI"require": anything elseThis is used for the following cases:
mode is buildbot, siteInfo, accounts and addons are not retrieved
because they are also passed using another internal option.Type: string
Configuration object used as default. This is an object serialized with JSON.
Type: object
Configuration object overriding any properties. This is a JavaScript object.
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 changevalue: new value of that propertyevent: build event when this change was applied, e.g. onPreBuildThe return value is a Promise resolving to an object with the following properties.
Type: object
Resolved configuration object.
Type: string?
Absolute path to the netlify.toml, if this file exists.
Type: string
Absolute path to the _headers, even if this file does not exist.
Type: string
Absolute path to the _redirects, even if this file does not exist.
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.
Type: string
The computed value of repositoryRoot.
Type: string
Resolved context. See the context option.
Type: string
Resolved git branch. See the branch option.
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.
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.
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.
Type: string
Netlify API token. This takes into account the token option but also some Netlify-specific environment
variables.
Type: NetlifyClient?
Netlify JavaScript client instance used to retrieve siteInfo,
accounts and addons.
Type: object?
When the buffer option is used, this contains two arrays stdout and stderr with the logs.
Type: object?
Site's environment variables. Each environment variable value is an object with the following properties:
value stringsources string[] among:
general: general environment variables set for all sitesaccount: environment variables set in the Netlify UI for a specific accountaddons: addon-specific environment variablesui: environment variables set in the Netlify UI for a specific siteconfigFile: environment variables set in netlify.toml$ netlify-config
Like resolveConfig(), but in the CLI. The return value is printed on stdout.
The CLI flags use the same options.
FAQs
Netlify config module
The npm package @netlify/config receives a total of 161,222 weekly downloads. As such, @netlify/config popularity was classified as popular.
We found that @netlify/config demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 17 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.