Migrate Build Plugins

By migrating your existing build plugin to an integration build event handler you can leverage the full power of the Netlify SDK. This provides additional benefits:

• It is no longer necessary to publish a package to NPM in order to hook into Netlify’s build events.
• You can create an interactive surface where you can configure and provide context for an integration using the Integration UI.

Migrate your build plugin

There are two ways to migrate an existing Netlify build plugin to an integration build event handler using the SDK.

• Import your existing build plugin into an integration
• Rewrite your existing build plugin as an integration

Import

You can import the existing npm package that contains your build plugin. This option could be useful if you want to start using the SDK without taking the time to rewrite your existing build plugin.

Importing is possible only if your build plugin is using functionality that is also supported by Build Event Handlers. The following features of Build Plugins do not have one-to-one equivalents in Build Event Handlers:

• The tools for working with user-supplied configuration values have changed drastically between Build Plugins and Build Event Handlers. Build Plugins use inputs whereas Build Event Handlers use buildConfig. There are changes to the way you specify what values are required, how users supply the required values, and how you access the values once supplied.
• Dynamic events are now known as Dynamic Build Event Handlers and follow a different type of configuration than before.

Follow these steps to migrate:

1. Create a new integration with the build boilerplate.
2. Install your existing build plugin as a dependency in your new integration project.
3. Import the build plugin in your /src/index.ts file.
4. Add any build plugin events you were using before with the .addBuildEventHandler method:

// src/index.ts
import { NetlifyIntegration } from "@netlify/sdk";
import YourBuildPlugin from "your-build-plugin";

const integration = new NetlifyIntegration();

integration.addBuildEventHandler("onPreBuild", YourBuildPlugin.onPreBuild);
integration.addBuildEventHandler("onPostBuild", YourBuildPlugin.onPostBuild);

export { integration };

Rewrite

You can rewrite your existing build plugin as an integration using the SDK.

Follow these steps to migrate:

1. Create a new integration with the build boilerplate.
2. Recreate any build events you were using before with the .addBuildEventHandler method:

// src/index.ts
const integration = new NetlifyIntegration();

// You can just add the function directly
integration.addBuildEventHandler("onPreBuild", () => {
  // add the functionality here
  console.log("This is my first Build Event Handler!");
});

// Or you can add a function that is exported from another file
import { myBuildHook } from "./myBuildHook";

integration.addBuildEventHandler("onPreBuild", myBuildHook);

Customize the integration flow to enable your build event handler

As outlined in the authentication doc, integrations have access to an onEnable method that runs after a user enables a published integration in the Netlify UI.

Build event handlers are not enabled by default when an integration is enabled, so you need to include an enableBuildEventHandlers() call in your integration. This is a required step before you publish your integration. If you don’t include this, your build event handlers won’t run for sites that have installed your integration.

If it doesn’t already exist, make sure you add the following to your integration code to enable the build event handlers when the integration is enabled:

// src/index.ts
integration.onEnable(async (_, { siteId, client }) => {
  // Build event handlers are disabled by default, so we need to
  // enable them when the integration is enabled.

  siteId && (await client.enableBuildEventHandlers(siteId));

  return {
    statusCode: 200,
  };
});

Build your integration

Once you’re done developing your build event handler, you can compile your code by using the following Netlify SDK utility tools command:

pnpm run build

yarn build

npm run build

The code is compiled to the folder .ntli.