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

To get started, run the following command to create a new extension:
```
npm create @netlify/sdk@latest
```
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. Learn about the required files in the anatomy of an extension doc.

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

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.

Hook into build events throughout the build-deploy lifecycle.
Use values and methods to develop the logic for your build event handler.
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 command:

pnpm run build

yarn build

npm 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.