Skip to content
Netlify SDK Docs Netlify SDK Docs 2.7.4

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.
    • A brief summary of the extension and its functionality that we’ll display in the Netlify UI. You can modify this value later.
  • 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:

├── extension.yaml
├── netlify.toml
├── node_modules
├── package-lock.json
├── package.json
├── src
│ ├── index.ts
│ └── edge-functions
│   └── hello-world.ts
│ └── functions
│   └── hello-world.mts
│ └── ui
│   └── index.ts
└── tsconfig.json
  • extension.yaml - The extension configuration file. This is where you configure the extension name, description, and other metadata.
  • netlify.toml - The Netlify configuration file. This is where you configure the settings for building and deploying your extension.
  • src/index.ts - The entrypoint for developing the extension.
  • src/edge-functions/ - The folder to store edge functions in, with a sample edge function (hello-world.ts) included. Note that the Netlify SDK only creates this file when you select the Edge Function Injection boilerplate.
  • src/functions/ - The folder to store serverless functions in, with a sample function (hello-world.mts) included. Note that the Netlify SDK only creates this file when you select the Function Injection boilerplate.
  • src/ui/index.ts - The entrypoint for developing the extension’s UI. Note that the Netlify SDK only creates this file when you select the Extension UI boilerplate.

2. Customize the extension

Now that you have the boilerplate for your extension, 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.

Or you can move to the next step now to preview and test the boilerplate extension.

3. Publish a private extension

To test your extension locally and, later in production, you need to publish it as a private extension on Netlify.

  1. Push to a Git repository
  2. Create a site to host the extension
  3. Create a private extension
  4. Update the slug in your extension.yml

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 to finish.

Learn more about publishing extensions and the publishing workflow.

Update the slug in your extension.yaml

When you published the private extension, the Netlify UI automatically appended a nanoid to the start of your Slug. Update the extension.yaml file in your project to use the updated slug.

  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.

4. Test locally

Now that you’ve published the extension as a private extension, you can test it locally.

  1. Start the local development server
  2. Install and check your extension’s surfaces
  3. Stop and clear local development settings

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.

  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.

5. Test in production

After you stop and clear your local development settings, you can test your private extension 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.

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