Skip to content
Netlify SDK Docs Netlify SDK Docs 2.15.0

Create a new extension

Learn the basics of extension development by creating, testing, and publishing an extension using the Netlify SDK.

For a complete working example of an extension built with SDK v2, refer to the Netlify extension showcase repository.

Migrating an existing integration to SDK v2?

If you have an existing SDK v1 integration, refer to the migration guide for an overview of what’s changed and a detailed guide of how to convert your SDK v1 integration to an SDK v2 extension.

Prerequisites

Windows users should run the Netlify SDK through WSL 2

Support for using the Netlify SDK on Windows is currently only available through WSL 2.

1. Create an extension with the SDK

To create a new extension with the Netlify SDK, run the create command using npm, pnpm, or yarn.

pnpm create @netlify/sdk@latest

Follow the prompts:

  • Install the @netlify/create-sdk package.
  • Specify where to create the extension.
  • Supply extension information, including:
    • A slug to use as the unique identifier for your extension and to create the package name. Once you publish an extension with this slug, you can’t change it.
  • Select the boilerplate code you want to generate.
    • At minimum, you need to select Extension UI because all extensions need to define UI for users to configure their extension.
    • If you prefer not to use a boilerplate, select none and follow the prompts to provide the permission scopes that the extension needs to function properly.
  • Select the package manager you want to use.

For example, you might select the Extension UI and Edge functions boilerplate to create an extension that will inject an edge function into the user’s site during the build step. The extension UI boilerplate will include a surface that we can customize to request certain information from the user when they configure the extension.

When the process completes, your selected directory will have the files you need to start building your extension and will include some example boilerplate code. Learn about the required files in the anatomy of an extension doc.

2. Set up local development

To set up local development and test your extension locally, you need to first deploy the extension on Netlify and publish it as a private extension on your team. The local development server uses the deployed extension’s configuration file (extension.yaml) to determine what surfaces to render in the local version of the Netlify UI.

  1. Push to a Git repository
  2. Create a site to host the extension
  3. Create a private extension
  4. Start the local development server
  5. Install and check your extension’s surfaces
  6. Stop and clear local development settings

For each extension you develop, you only need to complete steps 1-3 once to set up local development. Afterwards, you can jump straight to step 4 to start testing locally.

Push to a Git repository

If you haven’t already, push your extension code to a Git repository. Netlify will pull code from that repository in the next step.

Create a site to host the extension

Deploy your extension as a Netlify site. You will use this site solely for hosting the extension and managing updates to the code.

  1. Log in to the Netlify UI.
  2. Go to your team’s Sites page, open the Add new site menu, and select Import an existing project.
  3. Select your Git provider and then follow the prompts to log in and authenticate.
  4. Find and select the repository that contains your extension code.
  5. Deploy the site. You can review the status of the deploy on the Site overview page.

Learn more about creating a site from an existing repository in the Netlify user docs.

Create a private extension

Next, as a Team Owner, publish the extension as a private extension so you can preview it locally and then test it in production. Private extensions are only available to your team.

  1. In the Netlify UI, select the Extensions tab for your team. Make sure this is the same team that owns the deployed extension site.
  2. Select Created by your team and then select Create an extension.
  3. Enter a Display name, Slug, and Summary.
  4. Under Netlify extension site, select the Netlify site that hosts your extension code. Note that you can only associate a Netlify extension site with one published extension — you can’t publish multiple extensions with the same extension site.
  5. Select the Permission scopes for your extension.
  6. Select Create.
  7. The last step is to update the slug in your project’s extension.yaml to include the nanoid that the Netlify UI added during the publishing flow:
    1. In the Netlify UI, select the Extensions tab for your team and select Created by your team.
    2. Find the extension you just created and select it to go to the extension’s details page.
    3. Select Manage and find the Slug under Details.
    4. Copy the slug and paste it in your project’s extension.yaml file.
    5. Commit the update to Git, push the change to your repository, and redeploy the site that hosts your extension code.

Learn more about publishing extensions and the publishing workflow.

Start the local development server

The SDK includes support for a local development server that you can run to preview and test your extension UI.

Extension surfaces not loading? Make sure you deploy and publish

To run an extension locally, you need to first deploy it as a Netlify site and publish it as a private extension. If you skip these steps, the local development server won’t render your extension’s surfaces.

Make sure you also redeploy whenever you update the surfaces in extension.yaml to ensure the local development server reflects the latest configuration.

  1. Run the following command to start the local development server:

    pnpm run dev --open

    This command will start a local server and automatically open your browser to the extension development settings page in the Netlify UI. Only the authenticated user can access this URL.

  2. On the local extension development page, review and save your settings. By default, the settings use the URL of your local server and the extension’s slug from the extension.yaml file but you can edit them as needed.

    The Netlify UI saves these settings in your browser’s local storage and will persist them across sessions, so only you will be able to access the local development version of the extension.

Learn more about developing locally with extension UI.

Install and check your extension’s surfaces

Now that you have the local development server running, you can install and review your extension surfaces in the Netlify UI:

  1. Select your team name at the top of the Netlify UI, and then select Extensions.

  2. Select Created by your team and find your private extension in the list.

  3. Select the extension and then select Install on the details page.

    Note that this will actually install the extension on your team in production and it will remain installed even after you stop the local development server.

  4. You can now navigate to the various sections in the Netlify UI that contain your surfaces. For each of these surfaces, the Netlify UI will load the surface using the local development URL instead of the deployed version.

For example, if you selected the Extension UI and Edge functions boilerplate, you will find a configuration surface rendered:

  • on the extension’s details page under Extensions > [your extension’s details page] > Configuration

  • in a section listed under the top-level navigation for a site on your team

Learn more about extension UI and adding surfaces.

Stop and clear local development settings

Once you’re done testing locally, follow these steps to stop local development and clear the local settings stored in your browser.

  1. Stop the dev command process running in your terminal.
  2. In your browser, navigate back to the extension UI settings and select Delete settings. After you delete these settings, the Netlify UI will stop using the local version of your extension and will render the deployed surfaces from the published extension instead.

3. Customize the extension

Now that you have generated the boilerplate code and have the extension set up to develop and test locally, you can use the NetlifyExtension, NetlifyExtensionClient, and NetlifyConnector APIs to add custom logic and functionality as needed.

Learn more about how to develop the functionality for your extension in the following docs sections:

Extensions reliant on build events run on every site on a team

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.

4. Test in production

When you’re ready, you can test your extension in production. At this point, you should have already deployed and published your extension as a private extension while setting up local development. You can test the same private extension in production.

Make sure to stop and clear your local development settings

Before you test in production, make sure you stop and clear your local development settings. Otherwise, the app will render the local version of your extension.

To test in production:

  1. In the Netlify UI, navigate to the Extensions > Installed section for your team and confirm that your private extension is installed.
  2. Navigate to the various sections in the Netlify UI to review your extension UI surfaces and configure your extension as needed.
  3. Test the extension on your site.

5. Publish a public extension

In some cases, you may want to keep the extension private for only your team to use. For example, if your extension allows users to sync data from proprietary or bespoke data sources into Netlify Connect or Netlify Visual Editor.

But, if you want to make your extension available to others outside of your team, review our publishing docs to learn more about the publishing workflow. When you’re ready, you can publish it as a public extension.

Make sure you update the details.md file to add the recommended documentation for your users before you publish.

More resources

The following related resources may also be helpful to review:

Contact us for support

If you have questions or run into issues while creating your extension, please contact us through Netlify support or through the technology partner program.

Got it!

Your feedback helps us improve our docs.