Skip to content
Netlify Docs

Develop Build Plugins

In addition to installing plugins written by others, you can create your own. To learn how, check out the detailed reference information below and our Build Plugin template.

ES modules

Section titled “ES modules”

If you plan to use JavaScript, we recommend building new plugins with ES modules (ESM) but the examples below also include CommonJS (CJS) syntax for older plugins.

To use ESM, Node.js requires "type": "module" in your plugin’s package.json file.

Plug into events

Section titled “Plug into events”

Build Plugins run JavaScript or TypeScript code in response to different events happening during the build-deploy lifecycle.

For example, the onPreBuild event handler runs before your build command. The onPostBuild event handler runs after your site build has completed. The following event handlers are currently available:

  • onPreBuild: runs before the build command is executed.
  • onBuild: runs directly after the build command is executed and before Functions bundling.
  • onPostBuild: runs after the build command completes; after onBuild tasks and Functions bundling are executed; and before the deploy stage. This is when file-based uploads for Netlify Blobs occur. Can be used to prevent a build from being deployed.
  • onError: 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.
  • onSuccess: runs when the deploy succeeds. Can’t be used to prevent a build from being deployed.
  • onEnd: 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.

There are also event handlers that are available when running netlify dev:

  • onPreDev: runs before onDev.
  • onDev: runs directly before the dev command.

Anatomy of a plugin

Section titled “Anatomy of a plugin”

A plugin consists of two files:

  • A manifest.yml file in the package root with the plugin’s name at minimum:

    # manifest.yml
    

    name: netlify-plugin-hello-world

  • A JavaScript or TypeScript object that hooks onto a build event. For example, in JavaScript:

    // index.js
    

    export const onPreBuild = function() {
      console.log("Hello world from onPreBuild event!");
    }

The plugin defined above will output Hello world from onPreBuild event! right before the site’s build command is run.

The index.js file runs in a regular Node.js environment and can use any Node.js core methods and modules. Environment variables, redirects, headers, and build configuration can be accessed and modified with netlifyConfig.

Store both files together in a single folder. You can store this folder with your site code to run as a local plugin, or you can publish the plugin to npm.

Local plugins

Section titled “Local plugins”

You can run your own custom plugins from within your site repository without publishing to npm. To do this, save your plugin index.js and manifest.yml files into a folder in the repository. Then, using the file-based installation method, specify the absolute path to your plugin folder in the package field.

The following example installs a local plugin stored in /plugins/netlify-plugin-hello-world:

# netlify.toml


[[plugins]]
package = "/plugins/netlify-plugin-hello-world"

With a local plugin declared, you can verify it’s loading correctly by using the Netlify CLI to run the build locally.

Plugin values

Section titled “Plugin values”

When a plugin runs, it can receive certain data:

constants

Section titled “constants”

Each event handler includes a constants key.

// index.js


export const onPreBuild = function({ constants }) {
  console.log(constants);
}

The constants key contains the following values:

  • CONFIG_PATH: path to the Netlify configuration file. undefined if none was used.
  • PUBLISH_DIR: 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.
  • FUNCTIONS_SRC: 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_DIST: directory where built serverless functions are placed before deployment. Its value is always defined, but the target might not have been created yet.
  • IS_LOCAL: boolean indicating whether the build was run locally or on Netlify.
  • NETLIFY_BUILD_VERSION: version of Netlify Build as a major.minor.patch string.
  • SITE_ID: Netlify site ID.

Along with these constants, plugins can also access any of the environment variables that are available in the build environment.

inputs

Section titled “inputs”

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:

# manifest.yml


name: netlify-plugin-lighthouse
inputs:
  - name: output_path
    description: Path to save the generated HTML Lighthouse report
  - name: fail_deploy_on_score_thresholds
    description: Fail deploy if minimum threshold scores are not met
  - name: thresholds
    description: Key value mapping of thresholds that will fail the build when not passed

When you or a user install the plugin, the input names are used as keys with user-supplied values in the site netlify.toml file:

# netlify.toml


[[plugins]]
package = "./plugins/netlify-plugin-lighthouse"


  [plugins.inputs]
    output_path = "reports/lighthouse.html"
    fail_deploy_on_score_thresholds = "true"


  [plugins.inputs.thresholds]
    performance = 0.9
    accessibility = 0.9
    best-practices = 0.9
    seo = 0.9
    pwa = 0.9

These inputs values are passed into the plugin when the event handlers are being executed.

To access them in your plugin code you can use the following pattern:

// index.js


export const onPreBuild = function({ inputs }) {
  console.log(inputs.output_path);
  console.log(inputs.thresholds);
}

Input validation

Section titled “Input validation”

Plugin inputs can be validated using the inputs property in the plugin manifest.yml file:

# manifest.yml


name: netlify-plugin-lighthouse
inputs:
  - name: output_path
    required: false
    description: Path to save the generated HTML Lighthouse report
    default: "reports/lighthouse.html"
  - name: fail_deploy_on_score_thresholds
    required: false
    description: Fail deploy if minimum threshold scores are not met
  - name: thresholds
    required: false
    description: Key value mapping of thresholds that will fail the build when not passed

The inputs property is an array of objects with the following members:

  • name {string}: name of the input. Required.
  • description {string}: description of the input.
  • required {boolean}
  • default {any}: default value.

netlifyConfig

Section titled “netlifyConfig”

When an event handler executes, a site’s Netlify configuration is normalized by @netlify/config and passed as a netlifyConfig object. Normalization includes applying context-specific or branch-specific settings and combining settings from netlify.toml with build settings configured in the Netlify UI.

After normalization, plugins can access and modify most netlifyConfig properties during a site’s build. These include redirects, headers, and build configuration. If a site doesn’t use netlify.toml or build settings selections in the Netlify UI, netlifyConfig and its properties contain default build settings.

Here’s a list of modifiable properties:

And here’s a plugin code sample that modifies several of the above properties.

// index.js


export const onPreBuild = function({ netlifyConfig }) {
  const newCommand = `node YOUR_SCRIPT.js`;


  // Run a script after the build command
  netlifyConfig.build.command = netlifyConfig.build.command
    ? `${netlifyConfig.build.command} && ${newCommand}`
    : newCommand;


  // Modify build command's environment variables
  netlifyConfig.build.environment.DATABASE_URI = getDatabaseUri();


  // Add redirects
  netlifyConfig.redirects.push({
    from: "/ORIGIN_PATH",
    to: "/DESTINATION_PATH",
  });


  // Add headers
  netlifyConfig.headers.push({
    for: "/YOUR_PATH",
    values: { YOUR_HEADER_NAME: "YOUR_HEADER_VALUE" },
  });


  // Add edge functions
  netlifyConfig.edge_functions
    ? netlifyConfig.edge_functions.push({ path: '/YOUR_PATH', function: 'YOUR_EDGE_FUNCTION' })
    : (netlifyConfig.edge_functions = [{ path: '/YOUR_PATH', function: 'YOUR_EDGE_FUNCTION' }])
}

packageJson

Section titled “packageJson”

Each plugin event handler includes a packageJson argument. 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.

To access the packageJson object in your plugin code, use the following pattern:

// index.js


export const onPreBuild = function({ packageJson }) {
  console.log(packageJson);
}

Environment variables

Section titled “Environment variables”

Plugins can access build environment variables two different ways:

  • process.env: includes all Netlify build environment variables and any variables you declare using the Netlify UI or TOML. We recommend you use this when you only need to get values during the build process.
  • netlifyConfig.build.environment: includes only the variables you declare using the Netlify UI or TOML. We recommend you use this when you need to modify values during the build process.

Visit our Forums for a verified Support Guide on how to access environment variables during your site build.

Plugin methods

Section titled “Plugin methods”

We’ve provided a number of utilities and API methods to assist you in writing plugins.

Utilities

Section titled “Utilities”

Several utilities are provided with the utils argument to event handlers:

  • build: used to report errors or cancel builds
  • status: used to display information in the deploy summary
  • cache: used to cache files between builds
  • run: used to run commands and processes
  • git: used to retrieve Git-related information such as the list of modified/created/deleted files
// index.js


export const onPreBuild = async function({ utils: { build, status, cache, run, git } }) {
  await run.command("eslint src/ test/");
}

Error reporting

Section titled “Error reporting”

Exceptions thrown inside event handlers are reported in logs as bugs. Instead of using the onError event to handle exceptions, plugins should rely on try/catch/finally blocks and use utils.build:

// index.js


export const onPreBuild = function({ utils }) {
  try {
    badMethod();
  } catch (error) {
    utils.build.failBuild("YOUR_FAILURE_MESSAGE");
  }
}

The following methods are available depending on the error’s type:

  • utils.build.failBuild("YOUR_MESSAGE"): method that fails the build - the build in your dashboard would show “Failed”. Use this to indicate something went wrong.
  • utils.build.failPlugin("YOUR_MESSAGE"): method that fails the plugin but not the build.
  • utils.build.cancelBuild("YOUR_MESSAGE"): method that cancels the build - the dashboard would show “Cancelled” for that build. Use this to indicate that the build is being cancelled as planned.

utils.build.failBuild(), utils.build.failPlugin() and utils.build.cancelBuild() can specify an options object with the following properties:

  • error: original Error instance. Its stack trace will be preserved and its error message will be appended to the "YOUR_MESSAGE" argument.
// index.js


export const onPreBuild = function({ utils }) {
  try {
    badMethod();
  } catch (error) {
    utils.build.failBuild("YOUR_FAILURE_MESSAGE", { error });
  }
}

Logging

Section titled “Logging”

Anything logged to the console will be printed in the build logs.

// index.js


export const onPreBuild = function() {
  console.log("This is printed in the build logs");
}

If you’d prefer to make the information more visible, utils.status.show() can be used to display them in the deploy summary instead.

// index.js


export const onPreBuild = function({ utils }) {
  utils.status.show({
    // Optional. Default to the plugin’s name followed by a generic title.
    title: "Main title",
    // Required.
    summary: "Message below the title",
    // Optional. Empty by default.
    text: "Detailed information shown in a collapsible section",
  });
}

Only one status is shown per plugin. Calling utils.status.show() twice overrides the previous status.

This is meant for successful information. Errors should be reported with utils.build.* instead.

Asynchronous code

Section titled “Asynchronous code”

Asynchronous code can be achieved by using async methods:

// index.js


export const onPreBuild = async function({ utils }) {
  try {
    await doSomethingAsync();
  } catch (error) {
    utils.build.failBuild("YOUR_FAILURE_MESSAGE", { error });
  }
}

Any thrown Error or rejected Promise that is not handled by utils.build will be shown in the build logs as a plugin bug.

// index.js


export const onPreBuild = async function({ utils }) {


  // Any error thrown inside this function will be shown
  // in the build logs as a plugin bug.


  await doSomethingAsync();
}

Plugins end as soon as their methods end. Therefore you should await any asynchronous operation. The following examples show invalid code and the way to fix it.

// index.js
// Example of how to use callbacks.


const { promisify } = require("util");


// VALID EXAMPLE: please use this.
// This callback will be awaited.
export const onPostBuild = async function({ utils }) {
  const response = await promisify(doSomethingAsync)();


  console.log(response);
}


// INVALID EXAMPLE: do not use this.
// This callback will not be awaited.
export const onPostBuild = function({ utils }) {
  doSomethingAsync((error, response) => {
    console.log(response);
  })
}
 
// index.js
// Example of how to use events.


const pEvent = require("p-event");


// VALID EXAMPLE: please use this.
// This event will be awaited.
export const onPreBuild = async function({ utils }) {
  const emitter = doSomethingAsync();


  emitter.start();


  const response = await pEvent(emitter, "response");


  console.log(response);
}


// INVALID EXAMPLE: do not use this.
// This event will not be awaited.
export const onPreBuild = function({ utils }) {
  const emitter = doSomethingAsync();


  emitter.on("response", response => {
    console.log(response)
  });


  emitter.start()
}
 
// index.js
// Example of how to use `Array.forEach()`.


// VALID EXAMPLE: please use this.
// This callback will be awaited.
export const onPostBuild = async function({ utils }) {
  await Promise.all(
    array.map(async () => {
      await doSomethingAsync()
    }),
  );
}


// INVALID EXAMPLE: do not use this.
// This callback will not be awaited.
export const onPostBuild = function({ utils }) {
  array.forEach(async () => {
    await doSomethingAsync();
  });
}

Dynamic events

Section titled “Dynamic events”

Some plugins trigger different events depending on the user’s inputs. This can be achieved by returning the plugin object from a function instead.

// index.js


export default function helloWorldPlugin(inputs) {
  if (inputs.before) {
    return {
      onPreBuild: () => {
        console.log("Hello world from onPreBuild event!");
      },
    }
  } else {
    return {
      onPostBuild: () => {
        console.log("Hello world from onPostBuild event!");
      },
    }
  }
};