Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

Hook into build events

Build Event Handlers run JavaScript code in response to different events during Netlify’s build-deploy lifecycle.

For example, the onPreBuild event handler runs before the site’s build command. The onPostBuild event handler runs after the site build is complete.

src/index.ts
integration.addBuildEventHandler("onPreBuild", () => {
  console.log("Hello there.");
});

The following event handlers are currently available during build:

  • onPreBuild: runs before the build command is executed. If your integration includes functions and/or edge functions, Netlify injects them at this step before running your build event handlers.
  • onBuild: runs directly after the build command is executed and before Functions bundling.
  • onPostBuild: runs after the build command completes; after onBuild tasks and Functions bundling are executed; and before the deploy stage. This is when file-based uploads for Netlify Blobs occur. Can be used to prevent a build from being deployed.
  • onError: runs when an error occurs in the build or deploy stage, failing the build. Can’t be used to prevent a build from being deployed.
  • onSuccess: runs when the deploy succeeds. Can’t be used to prevent a build from being deployed.
  • onEnd: runs after completion of the deploy stage, regardless of build error or success; is useful for resources cleanup. Can’t be used to prevent a build from being deployed.

Hook into local development server events

When the user of your integration runs a local build of their site using the Netlify CLI’s build command, the event handlers that are mentioned above will run.

You can also take advantage of the following event handlers that are available when a user runs netlify dev:

  • onPreDev: runs before onDev. If your integration includes functions and/or edge functions, Netlify injects them at this step before running your build event handlers.
  • onDev: runs directly before the dev command.

If you set up an event handler for onPreBuild or onBuild, we recommend that you also set up an event handler for onPreDev or onDev to ensure that your integration works as expected when running in a local development server.