Skip to content
Netlify SDK Docs Netlify SDK Docs 1.38.2

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

Not recommended

While this option does have the benefit of being quicker to implement, it is not recommended as it will make maintenance difficult in the long run. This is because you will have to maintain two separate projects, one for your build plugin and one for your integration.

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 enablement flow

As outlined in the enablement flow doc, integrations have access to an onEnable method that runs after a user enables a published integration in the Netlify UI. You can add logic to customize the flow as needed.

src/index.ts
integration.onEnable(async (_, { siteId, client }) => {
  // add any custom logic here


  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

The code is compiled to the folder .ntli.