Skip to content
Netlify SDK Docs Netlify SDK Docs 2.26.3

Debug and test a build event handler

While developing your build event handler, you can test it locally to check if it works as expected.

Prepare your test project

To get ready to test your build event handler locally, do the following:

  1. Have a test project repository and your extension repository on your local machine.
  2. Create a test project on Netlify.
  3. Install the Netlify CLI with npm install netlify-cli -g.
  4. Make sure your test project is a git repository by running git init in the root of your test project.
  5. Log in to your Netlify account with netlify login.
  6. Link your local test project to the test project you created on Netlify by running netlify link.
  7. Create a netlify.toml file in the root of your test project with the following configuration:
netlify.toml
# Use your extension’s slug as the name
[[integrations]]
   name = "my-extension"


[integrations.dev]
  # Set the "path" as the path from your test project to your extension’s build folder.
  path = "../path/to/extension/repository"
  # The following forces the extension to be used when building the test project.
  force_run_in_build = true

You don’t have to build your build event handler yet

Normally, you have to build your build event handler to compile the code to the .ntli folder. But, you can skip this step when testing locally. The netlify build command you run while testing, as described below, automatically builds your build event handler in addition to building the test project.

Test locally on your test project

Now that your test project is ready, you can test your extension’s build event handler locally. To do so, run the following command for your test project in your terminal:

netlify build --context=dev

This runs a build of your test project while using your extension’s build event handler. You can now make changes to your extension’s build event handler and check the results in your terminal whenever you run the command above. Any console.log statements will show in the local build log.

Next steps

When you’re ready, you can publish your extension as a private extension and test it with a project in production.

Got it!

Your feedback helps us improve our docs.