Get started with Build Event Handlers

This page will help you get started with creating an integration that uses Build Event Handlers. It describes how to generate the boilerplate code, what the required files and basic scaffolding are, and how to build your build event handler.

Create a build event handler

1. To get started, run the following command to create a new integration:

   npm create @netlify/sdk@latest

2. Then, follow the prompts to add the build boilerplate.

   The Netlify SDK will scaffold the basic structure needed for your build event handler which includes these required files:

   • src/index.ts
   • package.json

   The src/index.ts file is the entrypoint for your integration and is listed in the main property of your package.json.

3. Inside the src/index.ts file, declare an instance of NetlifyIntegration and call the method addBuildEventHandler to create your first build event handler.

   // src/index.ts
   import { NetlifyIntegration } from "@netlify/sdk";
   
   const integration = new NetlifyIntegration();
   
   integration.addBuildEventHandler("onPreBuild", () => {
     console.log("This is my first build event handler!");
   });

Customize the integration flow to enable your build event handler

As outlined in the authentication doc, integrations have access to an onEnable method that runs after a user enables a published integration in the Netlify UI.

Build event handlers are not enabled by default when an integration is enabled, so you need to include an enableBuildEventHandlers() call in your integration. This is a required step before you publish your integration. If you don’t include this, your build event handlers won’t run for sites that have installed your integration.

If it doesn’t already exist, make sure you add the following to your integration code to enable the build event handlers when the integration is enabled:

// src/index.ts
integration.onEnable(async (_, { siteId, client }) => {
  // Build event handlers are disabled by default, so we need to
  // enable them when the integration is enabled.

  siteId && (await client.enableBuildEventHandlers(siteId));

  return {
    statusCode: 200,
  };
});

Develop your build event handler

Now that you’ve added a Build Event Handlers component to your integration, you can tailor it to fit your needs.

• Hook into build events throughout the build-deploy lifecycle.
• Use values and methods to develop the logic for your build event handler.
• Call an API handler from your build event handler to interact with the Integration API or Netlify API.
• Debug and test your build event handler to make sure it works as expected.

Build your build event handler

Once you’re done developing your build event handler, you can compile your code by using the following Netlify SDK utility tools command:

pnpm run build

yarn build

npm run build

The code is compiled to the folder .ntli.

Next steps

• If your integration requires configuration values from the user, use the Integration UI component to create an interactive surface for user input.
• Learn how to publish your integration so that users can enjoy your build event handler.