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