@netlify/build 18.15.0 → 18.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netlify/build",
-  "version": "18.15.0",
+  "version": "18.15.1",
   "description": "Netlify build module",
   "main": "src/core/main.js",
   "types": "types/index.d.ts",
@@ -9,7 +9,8 @@
   },
   "files": [
     "src/**/*.js",
-    "src/**/*.yml"
+    "src/**/*.yml",
+    "types/**/*.d.ts"
   ],
   "author": "Netlify Inc.",
   "contributors": [

package/types/config/build.d.ts

@@ -0,0 +1,61 @@
+import { JSONValue } from '../utils/json_value'
+
+interface NetlifyPlugin {
+  package: string
+  inputs: JSONValue
+}
+
+/* eslint-disable camelcase -- some properties are named in snake case in this API */
+
+export interface Build {
+  /**
+   * Includes a site's [build command](https://docs.netlify.com/configure-builds/get-started/#definitions)
+   */
+  command?: string
+
+  /**
+   * the path to your static content folder
+   */
+  publish: string
+  base: string
+  services: Record<string, unknown>
+
+  /**
+   * Allows specifying a Bash command that will be run from the base directory to determine whether the site needs rebuilding or not.
+   * Check out our [ignore builds](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/) doc for more information on the default ignore behavior and details about constructing a custom ignore command.
+   */
+  ignore?: string
+
+  /**
+   * Includes the path to a site's [Edge Handlers directory](https://docs.netlify.com/edge-handlers/configure-and-build/#choose-an-edge-handlers-directory)
+   */
+  edge_handlers?: string
+  /**
+   * Contains a site's [environment variables](https://docs.netlify.com/configure-builds/environment-variables/#netlify-configuration-variables)
+   */
+  environment: Partial<Record<string, string>>
+  /**
+   * Includes options for [post processing](https://docs.netlify.com/configure-builds/file-based-configuration/#post-processing) HTML, CSS, JavaScript, and images
+   */
+  processing: {
+    skip_processing?: boolean
+    css: {
+      bundle?: boolean
+      minify?: boolean
+    }
+    js: {
+      bundle?: boolean
+      minify?: boolean
+    }
+    html: {
+      pretty_url?: boolean
+    }
+    images: {
+      compress?: boolean
+    }
+  }
+
+  plugins: readonly NetlifyPlugin[]
+}
+
+/* eslint-enable camelcase */

package/types/config/functions.d.ts

@@ -0,0 +1,38 @@
+type GlobPattern = string
+
+/* eslint-disable camelcase -- some properties are named in snake case in this API */
+type FunctionsObject = {
+  /**
+   * string that includes the path to a site's [functions directory](https://docs.netlify.com/functions/configure-and-deploy/#configure-the-functions-folder)
+   */
+  directory: string
+} & (
+  | {
+      /**
+       * the function bundling method used in [`@netlify/zip-it-and-ship-it`](https://github.com/netlify/zip-it-and-ship-it).
+       */
+      node_bundler: 'zisi'
+    }
+  | {
+      /**
+       * the function bundling method used in [`@netlify/zip-it-and-ship-it`](https://github.com/netlify/zip-it-and-ship-it).
+       */
+      node_bundler: 'esbuild'
+
+      /**
+       * a list of Node.js modules that are copied to the bundled artifact without adjusting their source or references during the bundling process.
+       * This property helps handle dependencies that can’t be inlined, such as modules with native add-ons.
+       */
+      external_node_modules: string[]
+
+      /**
+       * a list of additional paths to include in the function bundle. Although our build system includes statically referenced files (like `require("./some-file.js")`) by default, `included_files` lets you specify additional files or directories and reference them dynamically in function code. You can use `*` to match any character or prefix an entry with `!` to exclude files. Paths are relative to the [base directory](https://docs.netlify.com/configure-builds/get-started/#definitions-1).
+       */
+      included_files: string[]
+
+      ignored_node_modules: string[]
+    }
+)
+/* eslint-enable camelcase */
+
+export type Functions = Record<GlobPattern, FunctionsObject>

package/types/config/netlify_config.d.ts

@@ -0,0 +1,51 @@
+import { Many } from '../utils/many'
+
+import { Build } from './build'
+import { Functions } from './functions'
+
+type HttpStatusCode = number
+
+interface Redirect {
+  from: string
+  to: string
+  status?: HttpStatusCode
+  force: boolean
+  signed?: string
+  query: Partial<Record<string, string>>
+  headers: Partial<Record<string, string>>
+  conditions: Record<'language' | 'role' | 'country', readonly string[]>
+}
+
+interface Header {
+  for: string
+  values: Partial<Record<string, Many<string, 'mutable'>>>
+}
+
+interface EdgeHandler {
+  path?: `/${string}`
+  handler: string
+}
+
+/* eslint-disable camelcase -- some properties are named in snake case in this API */
+
+interface NetlifyConfig {
+  /**
+   * array of redirects with their modifiable options
+   */
+  redirects: Redirect[]
+  /**
+   * array of headers with their modifiable options
+   */
+  headers: Header[]
+  /**
+   * array of Edge Handlers with their modifiable options
+   */
+  edge_handlers: EdgeHandler[]
+  /**
+   * object with options for modifying [functions](https://docs.netlify.com/configure-builds/file-based-configuration/#functions)
+   */
+  functions: Functions
+  build: Build
+}
+
+/* eslint-enable camelcase */

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './netlify_event'
+export * from './netlify_plugin'
+export * from './netlify_plugin_options'

package/types/netlify_event.d.ts

@@ -0,0 +1,5 @@
+import { NetlifyPluginOptions } from './netlify_plugin_options'
+
+export interface NetlifyEvent<PluginOptions extends NetlifyPluginOptions = NetlifyPluginOptions> {
+  (options: PluginOptions): void | Promise<void>
+}

package/types/netlify_plugin.d.ts

@@ -0,0 +1,29 @@
+import { NetlifyEvent } from './netlify_event'
+import { NetlifyPluginOptions } from './netlify_plugin_options'
+
+export interface NetlifyPlugin {
+  /**
+   * Runs before the build command is executed.
+   */
+  onPreBuild?: NetlifyEvent
+  /**
+   * runs directly after the build command is executed and before Functions? bundling and Edge Handlers bundling.
+   */
+  onBuild?: NetlifyEvent
+  /**
+   * runs after the build command completes; after onBuild? tasks, Functions? bundling, and Edge Handlers bundling are executed; and before the deploy stage. Can be used to prevent a build from being deployed.
+   */
+  onPostBuild?: NetlifyEvent
+  /**
+   * runs when an error occurs in the build or deploy stage, failing the build. Can’t be used to prevent a build from being deployed.
+   */
+  onError?: NetlifyEvent<NetlifyPluginOptions & { error: Error }>
+  /**
+   * runs when the deploy succeeds. Can’t be used to prevent a build from being deployed.
+   */
+  onSuccess?: NetlifyEvent
+  /**
+   * runs after completion of the deploy stage, regardless of build error or success; is useful for resources cleanup. Can’t be used to prevent a build from being deployed.
+   */
+  onEnd?: NetlifyEvent<NetlifyPluginOptions & { error?: Error }>
+}

package/types/netlify_plugin_options.d.ts

@@ -0,0 +1,56 @@
+import { NetlifyConfig } from './config/netlify_config'
+import { NetlifyPluginUtils } from './options/netlify_plugin_utils'
+
+export interface NetlifyPluginOptions {
+  constants: {
+    /**
+     * path to the Netlify configuration file.
+     * `undefined` if none was used.
+     */
+    CONFIG_PATH?: string
+    /**
+     * directory that contains the deploy-ready HTML files and assets generated by the build. Its value is always defined, but the target might not have been created yet.
+     */
+    PUBLISH_DIR: string
+    /**
+     * the directory where function source code lives.
+     * `undefined` if no `netlify/functions` directory exists in the base directory and if not specified by the user.
+     */
+    FUNCTIONS_SRC?: string
+    /**
+     * the directory where built serverless functions are placed before deployment. Its value is always defined, but the target might not have been created yet.
+     */
+    FUNCTIONS_DIST: string
+    /**
+     * the directory where Edge Handlers source code lives.
+     * `undefined` if no `netlify/edge-handlers` directory exists in the base directory and if not specified in `netlify.toml`.
+     */
+    EDGE_HANDLERS_SRC?: string
+    /**
+     * boolean indicating whether the build was [run locally](https://docs.netlify.com/cli/get-started/#run-builds-locally) or on Netlify
+     */
+    IS_LOCAL: boolean
+    /**
+     * version of Netlify Build as a `major.minor.patch` string
+     */
+    NETLIFY_BUILD_VERSION: string
+    /**
+     * the Netlify site ID
+     */
+    SITE_ID: string
+  }
+  /**
+   * If your plugin requires additional values from the user, you can specify these requirements in an `inputs` array in the plugin’s [`manifest.yml` file](https://docs.netlify.com/configure-builds/build-plugins/create-plugins/#anatomy-of-a-plugin).
+   */
+  inputs: Partial<Record<string, string>>
+  /**
+   * @see https://docs.netlify.com/configure-builds/build-plugins/create-plugins/#netlifyconfig
+   */
+  netlifyConfig: NetlifyConfig
+  /**
+   * When an event handler executes, the contents of the `package.json` in a site's base directory get passed to a plugin.
+   * The data fields are normalized to prevent plugin errors. If the site has no `package.json`, the argument is an empty object.
+   */
+  packageJson: Partial<Record<string, string>>
+  utils: NetlifyPluginUtils
+}

package/types/options/index.d.ts

@@ -0,0 +1 @@
+export * from './netlify_plugin_utils'

package/types/options/netlify_plugin_build_util.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Report errors or cancel builds
+ */
+export type NetlifyPluginBuildUtil = Record<
+  'failBuild' | 'failPlugin' | 'cancelBuild',
+  (message: string, options?: { error: Error }) => void
+>

package/types/options/netlify_plugin_cache_util.d.ts

@@ -0,0 +1,39 @@
+import { Many } from '../utils/many'
+
+/**
+ * Cache files between builds
+ */
+export type NetlifyPluginCacheUtil = {
+  save(
+    path: Many<string>,
+    options?: {
+      ttl?: number
+      digests?: string[]
+      /**
+       * @default `process.cwd()`
+       */
+      cwd?: string
+    },
+  ): Promise<boolean>
+  list(options: {
+    /**
+     * @default `process.cwd()`
+     */
+    cwd?: string
+    /**
+     * @default 1
+     */
+    depth?: number
+  }): Promise<string[]>
+} & Record<
+  'restore' | 'remove' | 'has',
+  (
+    path: Many<string>,
+    options?: {
+      /**
+       * @default `process.cwd()`
+       */
+      cwd?: string
+    },
+  ) => Promise<boolean>
+>

package/types/options/netlify_plugin_git_util.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Retrieve Git-related information such as the list of modified/created/deleted files
+ * @see https://github.com/netlify/build/blob/master/packages/git-utils/README.md
+ */
+export interface NetlifyPluginGitUtil {
+  fileMatch(globPattern: string): readonly string[]
+  /**
+   * Array of all modified files.
+   */
+  modifiedFiles: readonly string[]
+  /**
+   * Array of all created files.
+   */
+  createdFiles: readonly string[]
+  /**
+   * Array of all deleted files.
+   */
+  deletedFiles: readonly string[]
+  /**
+   * Array of commits with details.
+   */
+  commits: ReadonlyArray<{
+    sha: string
+    parents: string
+    author: {
+      name: string
+      email: string
+      date: string
+    }
+    committer: {
+      name: string
+      email: string
+      date: string
+    }
+    message: string
+  }>
+  /**
+   * How many lines of code have changed
+   */
+  linesOfCode(): Promise<number>
+}

package/types/options/netlify_plugin_run_util.d.ts

@@ -0,0 +1,24 @@
+import { Options as ExecaOptions, ExecaChildProcess } from 'execa'
+
+type NetlifyPluginRunUtilOptions = Omit<ExecaOptions, 'preferLocal'> & {
+  /**
+   * @default true
+   */
+  preferLocal?: ExecaOptions['preferLocal']
+}
+
+type NetlifyPluginRunUtilResult = ExecaChildProcess
+
+/**
+ * Run commands and processes
+ * @see https://github.com/netlify/build/blob/master/packages/run-utils/README.md
+ */
+export interface NetlifyPluginRunUtil {
+  (
+    file: string,
+    // eslint-disable-next-line fp/no-arguments -- params are named `arguments` in the docs. Unrelated to JS's `arguments`
+    arguments?: readonly string[],
+    options?: NetlifyPluginRunUtilOptions,
+  ): Promise<NetlifyPluginRunUtilResult>
+  command(command: string, options?: NetlifyPluginRunUtilOptions): Promise<NetlifyPluginRunUtilResult>
+}

package/types/options/netlify_plugin_status_util.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Display information in the deploy summary
+ */
+export interface NetlifyPluginStatusUtil {
+  /**
+   * Only one status is shown per plugin.
+   * Calling `utils.status.show()` twice overrides the previous status.
+   */
+  show(options: {
+    /**
+     * Default to the plugin's name followed by a generic title.
+     */
+    title?: string
+    /**
+     * Message below the title
+     */
+    summary: string
+    /**
+     * Detailed information shown in a collapsible section.
+     * @default ""
+     */
+    text?: string
+  }): void
+}

package/types/options/netlify_plugin_utils.d.ts

@@ -0,0 +1,13 @@
+import { NetlifyPluginBuildUtil } from './netlify_plugin_build_util'
+import { NetlifyPluginCacheUtil } from './netlify_plugin_cache_util'
+import { NetlifyPluginGitUtil } from './netlify_plugin_git_util'
+import { NetlifyPluginRunUtil } from './netlify_plugin_run_util'
+import { NetlifyPluginStatusUtil } from './netlify_plugin_status_util'
+
+export interface NetlifyPluginUtils {
+  build: NetlifyPluginBuildUtil
+  status: NetlifyPluginStatusUtil
+  cache: NetlifyPluginCacheUtil
+  run: NetlifyPluginRunUtil
+  git: NetlifyPluginGitUtil
+}

package/types/utils/json_value.d.ts

@@ -0,0 +1 @@
+export type JSONValue = string | number | boolean | null | { [key: string]: JSONValue } | Array<JSONValue>

package/types/utils/many.d.ts

@@ -0,0 +1,6 @@
+type ArrayByMode<T, Mode extends 'immutable' | 'mutable' = 'immutable'> = {
+  immutable: readonly T[]
+  mutable: T[]
+}[Mode]
+
+export type Many<T, Mode extends 'immutable' | 'mutable' = 'immutable'> = T | ArrayByMode<T, Mode>