1 | # Netlify Config
|
2 |
|
3 | This library loads, validates, and normalizes the Netlify configuration.
|
4 |
|
5 | Netlify can be configured:
|
6 |
|
7 | - In the [build settings](https://docs.netlify.com/configure-builds/get-started/).
|
8 | - In a [`netlify.toml`](https://docs.netlify.com/configure-builds/file-based-configuration/) file in the repository root
|
9 | directory or site `base` directory.
|
10 |
|
11 | # Install
|
12 |
|
13 | ```bash
|
14 | npm install @netlify/config
|
15 | ```
|
16 |
|
17 | # Usage (Node.js)
|
18 |
|
19 | ## getNetlifyConfig(options?)
|
20 |
|
21 | `options`: `object?`\
|
22 | _Return value_: `Promise<object>`
|
23 |
|
24 | ```js
|
25 | const getNetlifyConfig = require('@netlify/config')
|
26 |
|
27 | const exampleFunction = async function () {
|
28 | const { config, configPath, buildDir, context, branch, token, siteInfo } = await getNetlifyConfig(options)
|
29 | // {
|
30 | // "siteInfo": {
|
31 | // "id": "418b94bc-93cd-411a-937a-ae4c734f17c4",
|
32 | // "name": "mick",
|
33 | // "build_settings": {
|
34 | // "cmd": "",
|
35 | // "dir": "",
|
36 | // "env": { ... },
|
37 | // "functions_dir": "",
|
38 | // "base": "",
|
39 | // },
|
40 | // ...
|
41 | // },
|
42 | // "accounts": [
|
43 | // {
|
44 | // "name": "my team",
|
45 | // "slug": "me",
|
46 | // ...
|
47 | // },
|
48 | // ...
|
49 | // ],
|
50 | // "addons": [],
|
51 | // "env": {
|
52 | // "NODE_VERSION": { "sources": ["configFile"], "value": "16" },
|
53 | // ...
|
54 | // },
|
55 | // "configPath": "/home/me/code/cv-website/netlify.toml",
|
56 | // "buildDir": "/home/me/code/cv-website",
|
57 | // "repositoryRoot": "/home/me/code/cv-website",
|
58 | // "config": {
|
59 | // "functionsDirectory": "/home/me/code/cv-website/netlify/functions",
|
60 | // "functionsDirectoryOrigin": "default",
|
61 | // "functions": { "*": { "node_bundler": "esbuild" } },
|
62 | // "builders": { "*": { "node_bundler": "esbuild" } },
|
63 | // "plugins": [
|
64 | // {
|
65 | // "package": "@netlify/plugin-sitemap",
|
66 | // "inputs": {},
|
67 | // "origin": "config"
|
68 | // }
|
69 | // ],
|
70 | // "build": {
|
71 | // "publish": "/home/me/code/cv-website/build",
|
72 | // "publishOrigin": "default",
|
73 | // "command": "gulp build",
|
74 | // "commandOrigin": "config",
|
75 | // "functions": "/home/me/code/cv-website/netlify/functions"
|
76 | // }
|
77 | // },
|
78 | // "context": "production",
|
79 | // "branch": "main",
|
80 | // "token": "564194bc-12cd-511a-037a-be4c734f17c4"
|
81 | // }
|
82 | }
|
83 | ```
|
84 |
|
85 | ### Options
|
86 |
|
87 | The `options` are an optional `object` with the following properties.
|
88 |
|
89 | Those `options` are automatically set when using `@netlify/config` in the Netlify production CI or with Netlify CLI.
|
90 |
|
91 | #### debug
|
92 |
|
93 | _Type_: `boolean`\
|
94 | _Default value_: `false` unless the `NETLIFY_BUILD_DEBUG` environment variable is set.
|
95 |
|
96 | Prints debugging information showing the configuration being resolved.
|
97 |
|
98 | #### offline
|
99 |
|
100 | _Type_: `boolean`\
|
101 | _Default value_: `false`
|
102 |
|
103 | Do not send requests to the Netlify API to retrieve site settings.
|
104 |
|
105 | #### buffer
|
106 |
|
107 | _Type_: `boolean`\
|
108 | _Default value_: `false`
|
109 |
|
110 | When using [`debug`](#debug), returns the `logs` instead of printing them on the console.
|
111 |
|
112 | #### config
|
113 |
|
114 | _Type_: `string`
|
115 |
|
116 | Path to the `netlify.toml`. It is either an absolute path or a path relative to the [`cwd`](#cwd).
|
117 |
|
118 | If not specified, it is searched in the following directories (by highest priority order):
|
119 |
|
120 | - `base` directory
|
121 | - [`repositoryRoot`](#repositoryRoot)
|
122 | - current directory
|
123 | - any parent directory
|
124 |
|
125 | Otherwise, no `netlify.toml` is used.
|
126 |
|
127 | #### repositoryRoot
|
128 |
|
129 | _Type_: `string`\
|
130 | _Default value_: see [`cwd`](#cwd)
|
131 |
|
132 | Repository root directory. This is used in the following cases:
|
133 |
|
134 | - Searching for the `netlify.toml` (see [`config`](#config))
|
135 | - When a `base` directory was specified, its path is relative to the repository root directory
|
136 | - The `functions`, `builders`, `edge_handlers` and `publish` directories are relative to the repository root directory
|
137 | or (if specified) the `base` directory
|
138 | - Determining the [build directory](#builddir)
|
139 |
|
140 | If not specified, it is automatically guessed by looking for any `.git` directory from the [`cwd`](#cwd), and up. If
|
141 | none is found, the [`cwd`](#cwd) is used instead.
|
142 |
|
143 | #### cwd
|
144 |
|
145 | _Type_: `string`\
|
146 | _Default value_: `process.cwd()`
|
147 |
|
148 | Current directory. This is used in the following cases:
|
149 |
|
150 | - Searching for the `netlify.toml` (see [`config`](#config))
|
151 | - Searching for the [`repositoryRoot`](#repositoryroot)
|
152 | - In a monorepo, when stepping inside a specific package in the console, that package is automatically used as `base`
|
153 | directory
|
154 |
|
155 | #### context
|
156 |
|
157 | _Type_: `string`\
|
158 | _Default value_: environment variable `CONTEXT`, or `"production"`
|
159 |
|
160 | [Deploy context](https://docs.netlify.com/site-deploys/overview/#deploy-contexts).
|
161 |
|
162 | The `netlify.toml` can contain `contexts.{CONTEXT}` properties, which are like `build` properties but only applied when
|
163 | `{CONTEXT}` matches.
|
164 |
|
165 | #### branch
|
166 |
|
167 | _Type_: `string`\
|
168 | _Default value_: environment variable `BRANCH`, current `git` branch, `"main"` or `"master"`.
|
169 |
|
170 | Same as [`context`](#context) but using a `git` branch name.
|
171 |
|
172 | #### token
|
173 |
|
174 | _Type_: `string`\
|
175 | _Default value_: environment variable `NETLIFY_AUTH_TOKEN`
|
176 |
|
177 | Netlify API token.
|
178 |
|
179 | This is used to retrieve [`siteInfo`](#siteinfo).
|
180 |
|
181 | #### host
|
182 |
|
183 | _Type_: `string`\
|
184 | _Default value_: `api.netlify.com`
|
185 |
|
186 | Host of the Netlify API.
|
187 |
|
188 | #### scheme
|
189 |
|
190 | _Type_: `string`\
|
191 | _Default value_: `https`
|
192 |
|
193 | Scheme/protocol of the Netlify API.
|
194 |
|
195 | #### pathPrefix
|
196 |
|
197 | _Type_: `string`\
|
198 | _Default value_: `/api/v1`
|
199 |
|
200 | Base path prefix of the Netlify API.
|
201 |
|
202 | #### siteId
|
203 |
|
204 | _Type_: `string`\
|
205 | _Default value_: environment variable `NETLIFY_SITE_ID`
|
206 |
|
207 | Netlify Site ID.
|
208 |
|
209 | This is used to retrieve [`siteInfo`](#siteinfo), [`accounts`](#accounts) and [`addons`](#addons).
|
210 |
|
211 | #### env
|
212 |
|
213 | _Type_: `object`
|
214 |
|
215 | Environment variable to use, in addition to the current `process.env`. This is used as the default values of other
|
216 | options.
|
217 |
|
218 | #### mode
|
219 |
|
220 | _Type_: `string`\
|
221 | _Default value_: `"require"`
|
222 |
|
223 | What is calling `@netlify/config`. Can be:
|
224 |
|
225 | - `"buildbot"`: Netlify production CI
|
226 | - `"cli"`: Netlify CLI
|
227 | - `"require"`: anything else
|
228 |
|
229 | This is used for the following cases:
|
230 |
|
231 | - if `mode` is `buildbot`, [`siteInfo`](#siteinfo), [`accounts`](#accounts) and [`addons`](#addons) are not retrieved
|
232 | because they are also passed using another internal option.
|
233 |
|
234 | #### defaultConfig
|
235 |
|
236 | _Type_: `string`
|
237 |
|
238 | Configuration object used as default. This is an object serialized with JSON.
|
239 |
|
240 | #### inlineConfig
|
241 |
|
242 | _Type_: `object`
|
243 |
|
244 | Configuration object overriding any properties. This is a JavaScript object.
|
245 |
|
246 | #### configMutations
|
247 |
|
248 | _Type_: `array`
|
249 |
|
250 | Array of changes to apply to the configuration. Each change must be an object with three properties:
|
251 |
|
252 | - `keys`: array of keys targetting the property to change
|
253 | - `value`: new value of that property
|
254 | - `event`: build event when this change was applied, e.g. `onPreBuild`
|
255 |
|
256 | ### Return value
|
257 |
|
258 | The return value is a `Promise` resolving to an `object` with the following properties.
|
259 |
|
260 | #### config
|
261 |
|
262 | _Type_: `object`
|
263 |
|
264 | Resolved configuration object.
|
265 |
|
266 | #### configPath
|
267 |
|
268 | _Type_: `string?`
|
269 |
|
270 | Absolute path to the `netlify.toml`, if this file exists.
|
271 |
|
272 | #### headersPath
|
273 |
|
274 | _Type_: `string`
|
275 |
|
276 | Absolute path to the `_headers`, even if this file does not exist.
|
277 |
|
278 | #### redirectsPath
|
279 |
|
280 | _Type_: `string`
|
281 |
|
282 | Absolute path to the `_redirects`, even if this file does not exist.
|
283 |
|
284 | #### buildDir
|
285 |
|
286 | _Type_: `string`
|
287 |
|
288 | Absolute path to the build directory.
|
289 |
|
290 | The build directory is the current directory in which most build operations, including the build command, execute. It is
|
291 | usually either the [`repositoryRoot`](#repositoryRoot) or (if specified) the `base` directory.
|
292 |
|
293 | #### repositoryRoot
|
294 |
|
295 | _Type_: `string`
|
296 |
|
297 | The computed value of [`repositoryRoot`](#repositoryRoot).
|
298 |
|
299 | #### context
|
300 |
|
301 | _Type_: `string`
|
302 |
|
303 | Resolved context. See the [`context`](#context) option.
|
304 |
|
305 | #### branch
|
306 |
|
307 | _Type_: `string`
|
308 |
|
309 | Resolved git branch. See the [`branch`](#branch) option.
|
310 |
|
311 | #### siteInfo
|
312 |
|
313 | _Type_: `object`
|
314 |
|
315 | Netlify Site information retrieved using the `getSite` Netlify API endpoint. This is used to retrieve Build settings set
|
316 | in the Netlify App: plugins, Build command, Publish directory, Functions directory, Base directory, Environment
|
317 | variables.
|
318 |
|
319 | This might be empty depending on the options passed.
|
320 |
|
321 | #### accounts
|
322 |
|
323 | _Type_: `object[]`
|
324 |
|
325 | Netlify accounts retrieved using the `listAccountsForUser` Netlify API endpoint. This is used to retrieve account-level
|
326 | environment variables.
|
327 |
|
328 | This might be empty depending on the options passed.
|
329 |
|
330 | #### addons
|
331 |
|
332 | _Type_: `object[]`
|
333 |
|
334 | Netlify addons retrieved using the `listServiceInstancesForSite` Netlify API endpoint. This is used to retrieve
|
335 | addon-specific environment variables.
|
336 |
|
337 | This might be empty depending on the options passed.
|
338 |
|
339 | #### token
|
340 |
|
341 | _Type_: `string`
|
342 |
|
343 | Netlify API token. This takes into account the [`token`](#token) option but also some Netlify-specific environment
|
344 | variables.
|
345 |
|
346 | #### api
|
347 |
|
348 | _Type_: `NetlifyClient?`
|
349 |
|
350 | Netlify [JavaScript client instance](https://github.com/netlify/js-client) used to retrieve [`siteInfo`](#siteinfo),
|
351 | [`accounts`](#accounts) and [`addons`](#addons).
|
352 |
|
353 | #### logs
|
354 |
|
355 | _Type_: `object?`
|
356 |
|
357 | When the [`buffer`](#buffer) option is used, this contains two arrays `stdout` and `stderr` with the logs.
|
358 |
|
359 | #### env
|
360 |
|
361 | _Type_: `object?`
|
362 |
|
363 | Site's environment variables. Each environment variable value is an object with the following properties:
|
364 |
|
365 | - `value` `string`
|
366 | - `sources` `string[]` among:
|
367 | - `general`: general environment variables set for all sites
|
368 | - `account`: environment variables set in the Netlify UI for a specific account
|
369 | - `addons`: addon-specific environment variables
|
370 | - `ui`: environment variables set in the Netlify UI for a specific site
|
371 | - `configFile`: environment variables set in `netlify.toml`
|
372 |
|
373 | # Usage (CLI)
|
374 |
|
375 | ```bash
|
376 | $ netlify-config
|
377 | ```
|
378 |
|
379 | Like [`getNetlifyConfig()`](getnetlifyconfigoptions), but in the CLI. The return value is printed on `stdout`.
|
380 |
|
381 | The CLI flags use the same options.
|