Skip to content
Netlify SDK Docs Netlify SDK Docs 2.25.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 site

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

  1. Have a test site repository and your extension repository on your local machine.
  2. Create a test site on Netlify.
  3. Install the Netlify CLI with npm install netlify-cli -g.
  4. Make sure your test site is a git repository by running git init in the root of your test site.
  5. Log in to your Netlify account with netlify login.
  6. Link your local test site to the test site you created on Netlify by running netlify link.
  7. Create a netlify.toml file in the root of your test site 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 site to your extension’s build folder.
  path = "../path/to/extension/repository"
  # The following forces the extension to be used when building the test site.
  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 site.

Test locally on your test site

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

netlify build --context=dev

This runs a build of your test site 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 site in production.

Got it!

Your feedback helps us improve our docs.