Skip to content

Get started with build event handlers

This page will help you get started with creating an extension that uses a build event handler to run during the build-deploy lifecycle for a site. 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 extension:

    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 extension and is listed in the main property of your package.json.

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

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

Note that when a user installs extensions on a team, build event handlers run during the build step for every site on that team. We recommend that you include logic to check for specific configuration before running.

Develop your build event handler

Now that you’ve added a build event handler to your extension, 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 command:

pnpm run build

The code is compiled to the folder .ntli.

Next steps

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

Got it!

Your feedback helps us improve our docs.