Skip to content
Netlify SDK Docs Netlify SDK Docs 2.26.1

Migrate Build Plugins

By migrating your existing build plugin to an extension 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 extension using the extension UI.

Migrate your build plugin

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

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

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 extension.

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 a build event handler. 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 extension with the Build Event Handler boilerplate.
  2. Install your existing build plugin as a dependency in your new extension 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 { NetlifyExtension } from "@netlify/sdk";
import YourBuildPlugin from "your-build-plugin";


const extension = new NetlifyExtension();


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


export { extension };

Rewrite

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

Follow these steps to migrate:

  1. Create a new extension with the Build Event Handler boilerplate.
  2. Recreate any build events you were using before with the .addBuildEventHandler method:
src/index.ts
const extension = new NetlifyExtension();


// You can just add the function directly
extension.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";


extension.addBuildEventHandler("onPreBuild", myBuildHook);

Build your extension

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

pnpm run build

The code is compiled to the folder .ntli.

Got it!

Your feedback helps us improve our docs.