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.
- Node.js 18.19.0 or later
- Netlify CLI
- TypeScript
Create a build event handler
-
To get started, run the following command to create a new extension:
-
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 themain
property of yourpackage.json
. -
Inside the
src/index.ts
file, declare an instance ofNetlifyExtension
and call the methodaddBuildEventHandler
to create your 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:
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.