Migration guide overview
SDK v2 offers a host of new functionality for building extensions with the SDK and for using extensions in the Netlify UI.
By migrating to SDK v2, you benefit from:
- brand new functionality to build custom UI using a React-based toolkit that integrates seamlessly into the Netlify UI
- updated connector APIs that allow you to build extensions for Netlify Visual Editor
- support for self-serve publishing of private and public extensions
- improved experience in the Netlify UI for users to find, install, and configure extensions in the new extensions directory
- improved developer experience with upgraded SDK APIs and tooling, plus new UI for managing extensions in the Netlify UI
You can upgrade from v1 to v2 without downtime for your current users.
Check out our example extension
For a complete working example of an extension built with SDK v2, refer to the Netlify extension showcase repository. You can also install it now on your team through the Showcase extension’s details page.
What happens if you don’t migrate
Integrations built and published with SDK v1 are automatically flagged as deprecated in the Netlify UI.
An integration built with SDK v1 will continue to function for teams and sites that currently have it installed, but users can’t install it on new sites or teams. Once a user uninstalls the integration, it cannot be installed again.
You can continue to push updates to your published integrations and these will be automatically available to users that have it installed.
We recommend that you migrate your integrations to extensions with SDK v2 now to take advantage of the new features and functionality, and so new users can continue to find and install your tools.
Comparing versions
Extensions built with SDK v2 support the same functionality that your SDK v1 integration does but with some key changes and additional features:
| SDK v1 | SDK v2 | |
|---|---|---|
| What you output with the SDK | integrations | extensions |
| Team-level installation | ✓ | ✓ |
| Site-level installation | ✓ | automatically installed on all sites on a team |
| Build event handlers, edge function injection, and function injection run on | enabled sites only | all sites |
| Support for build event handlers, connectors, edge function injection, function injection, endpoints, and OAuth | ✓ | ✓ |
| Support for developing connectors for Netlify Visual Editor | ✓ | |
| Custom surfaces in Netlify UI | ✓ | ✓ - new extension UI functionality |
| Self-serve publishing for private integrations / extensions | ✓ | ✓ |
| Self-serve publishing for public integrations / extensions | ✓ | |
In-app documentation using details.md | ✓ | |
| Unlisted extensions with a direct link | ✓ | |
| Extensions directory listing, under Extensions > Directory in the Netlify UI | ✓ | ✓ |
We’ve renamed Netlify Integrations to Netlify Extensions, along with all of the related APIs in the SDK, to better represent what you can build with the SDK. Some extensions integrate with external services, some add functionality that runs only within the Netlify platform, and some do both.
The following sections add more detail to some of the important changes noted above.
Extensions are installed on the team level only
With SDK v1, you could specify whether to enable the integration on the team level, site level, or both. With SDK v2, all extensions are installed on the team level.
Once a user installs the extension on their team, the extension can function on the team, site, and data layer, and in the visual editor — all depending on the logic you add to your extension.
If your integration includes custom logic for sites in onEnable and onDisable handlers, they will no longer work. You can specify this in your extension’s site configuration logic in createSiteConfiguration.
Tied to this update, integrationLevel is no longer available for use in the extension configuration file.
Build event handlers, edge function injection, and function injection run on every site
After a user installs your extension, all logic related to build event handlers, function injection, and edge function injection runs during the build step for every site the team owns.
It is important to be mindful of this and ensure your extension includes logic to early return if specific configuration is missing, for example, to minimize unnecessary impact to user sites and build times.
For example, you can confirm whether the user has set a required environment variable for the site before running.
import { NetlifyExtension } from '@netlify/sdk';
const extension = new NetlifyExtension();
extension.addBuildEventHandler('onPreBuild', async () => { const runBuildEventHandler = process.env.RUN_EXTENSION_VARIABLE; if (runBuildEventHandler) { console.log( 'This is an onPreBuild build event handler' ); return; } return;});
export { extension };Extension UI replaces Integration UI
One of the biggest changes in SDK v2 is the new extension UI functionality that replaces Integration UI. More than just a name change, the new functionality allows you to write a single-page React application that is rendered to sandboxed iFrames in a number of locations within the Netlify UI.
How to migrate
Follow the step-by-step migration guide to convert your existing SDK v1 integration to an SDK v2 extension.