Hook into build events

Build event handlers run JavaScript code in response to different events during Netlify’s build-deploy lifecycle.

For example, the onPreBuild event handler runs before the site’s build command. The onPostBuild event handler runs after the site build is complete.

extension.addBuildEventHandler("onPreBuild", () => {
  console.log("Hello there.");
});

Extensions reliant on build events run on every site on a team

After a user installs your extension, all logic related to build event handlers, function injection, and edge function injection runs during the build step for every site the team owns. It is important to be mindful of this and ensure your extension includes logic to early return if specific configuration is missing, for example, to minimize unnecessary impact to user sites and build times.

The following event handlers are currently available during build:

onPreBuild: runs before the build command is executed. If your extension includes functions and/or edge functions, Netlify injects them at this step before running your build event handlers.
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.

Add logic to only run on configured sites

After a user installs your extension on their team, your build event handler will run during the build step for every site the team owns. We recommend that you add conditional logic to your extension to minimize unnecessary impact to user sites and build times.

In this example, the extension checks that the user’s site has a required site environment variable before running. The extension creates the environment variable when the user configures the extension, so it will only exist if the extension is configured for that site. For an example of how to create environment variables using createOrUpdateVariables, refer to the extension-showcase repository.

import { NetlifyExtension } from '@netlify/sdk';

const extension = new NetlifyExtension();

extension.addBuildEventHandler('onPreBuild', async () => {
  const extensionConfigured = process.env.MY_EXTENSION_WAS_CONFIGURED_VARIABLE;
  if (extensionConfigured) {
    console.log(
      'This is an onPreBuild build event handler'
    );
    // Add your other build event handler logic here
    return;
  }
  return;
});

export { extension };

Hook into local development server events

When the user of your extension runs a local build of their site using the Netlify CLI’s build command, the event handlers that are mentioned above will run.

You can also take advantage of the following event handlers that are available when a user runs netlify dev:

onPreDev: runs before onDev. If your extension includes functions and/or edge functions, Netlify injects them at this step before running your build event handlers.
onDev: runs directly before the dev command.

If you set up an event handler for onPreBuild or onBuild, we recommend that you also set up an event handler for onPreDev or onDev to ensure that your extension works as expected when running in a local development server.

Got it!

Your feedback helps us improve our docs.

Hook into build events

Add logic to only run on configured sites

Hook into local development server events

Did you find this doc useful?

Got it!