Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

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.

Prerequisites

Windows users should run the Netlify SDK through WSL 2

Support for using the Netlify SDK on Windows is currently only available through WSL 2.

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 Event Handler 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 enablement flow

As outlined in the enablement flow doc, integrations have access to an onEnable method that runs after a user enables a published integration in the Netlify UI. You can add logic to customize the flow as needed.

src/index.ts
integration.onEnable(async (_, { siteId, client }) => {
  // add any custom logic here


  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.

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

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.