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 usebuildConfig
. 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:
- Create a new integration with the
build
boilerplate. - Install your existing build plugin as a dependency in your new integration project.
- Import the build plugin in your
/src/index.ts
file. - 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:
- Create a new integration with the
build
boilerplate. - 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
.