Publish extensions

Start by publishing your extension as a private extension for your team to use. You can then make it publicly available, with an option to keep it unlisted and accessible through a direct link only or to submit it for review and listing in the extensions directory.

If you haven’t already, review the publish and manage extensions overview to learn more about how extensions are presented in the Netlify UI and the overall publishing workflow.

You must be a Team Owner on Netlify to publish extensions. We recommend that you review the limitations before you begin.

Limitations

Please keep the following limitations in mind as you prepare to publish your extension:

Private extensions that are installed on a team cannot be deleted.
Public extensions cannot be changed back to private extensions.
Public extensions cannot be deleted.
Listed extensions cannot be changed back to unlisted.
Netlify sites that host the code for public extensions cannot be deleted.
Netlify teams that own public extensions cannot be deleted.
Netlify sites that host the code for extensions should not have site protections enabled.

If you need to delete an extension, site, or team impacted by the above limitations, please contact us.

Prepare your extension

Before you begin, please ensure you review the following sections to prepare your extension for publishing.

Configuration file

Make sure that your extension’s netlify.toml file includes the following:

[build]
command = "netlify-extension build"
publish = ".ntli/site/static"

[dev]
command = "netlify-extension dev"

[functions]
directory = "src/endpoints"

[[plugins]]
package = "@netlify/netlify-plugin-netlify-extension"

Documentation

Make sure your extension includes a details.md file in the root of the project with information for users on how to configure and use your extension. We’ll render this markdown on the extension’s details page.

We recommend that you include the following:

information about your extension and how it works
any requirements and known limitations
details on how to configure the extension once installed, including where to access your extension UI surfaces in the Netlify UI
links to other documentation
contact information for further support

If you would like to include images in your details.md, Netlify will read files from an assets folder at the root of your extension. You can then reference the image files using the relative path, for example /assets/image.png.

Metadata

Prepare the metadata that you will need to provide when you publish your extension:

Name: human-friendly name of the extension.
Slug: unique value used to identify the extension in the Netlify UI. When you publish your extension, a nanoid will be generated automatically and appended to the start of your slug.
Summary: brief summary of the extension and what it does. This will be displayed at the top of your extension details page and, if listed, on your extension’s card in the extensions directory.
Permission scopes: permission scopes that the extension needs to operate properly.

Use only the permission scopes you need

We recommend that you only request the permission scopes that are required for your extension to function properly. Are we missing a scope that you’d like to use? Let us know through the docs feedback form at the bottom of this page.

Publish a private extension

All extensions are published first as a private extension that is only available to your team. Publishing it as a private extension first allows you to test in production before you make it public.

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.

As a Team Owner, prepare your extension and then take the following steps to publish a private extension:

If you haven’t already, push your extension code to a Git repository. Netlify will pull code from that repository in the next step.
Deploy your extension as a Netlify site. Log in to the Netlify UI and create a new Netlify site by importing from the repository that contains your extension code. This site will be solely used for hosting the extension.
In the Netlify UI, select the Extensions tab for your team. Make sure this is the same team that owns your deployed extension site.
Select Created by your team and then select Create an extension.
Enter a Display name, Slug, and Summary.
Under Netlify extension site, select the Netlify site you created in step 2. Note that a Netlify extension site can only be associated with one published extension — you can’t publish multiple extensions with the same extension site.
Select the Permission scopes for your extension.
Select Create.
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.

Now that your extension is published, your team can access the private extension by navigating to Extensions in the Netlify UI and selecting Created by your team. You will notice the extension is labeled with a Private badge.

To learn how to install and use extensions with Netlify sites, review the extensions and integrations section in the Netlify user docs.

Extension sites should not have site protection enabled

The site that hosts your extension must be publicly available. If your team has Site Protection enabled, you must explicitly remove protection from the site’s production deploy. You can still have it enabled for non-production deploys, if needed. Learn how to configure site protection settings for a single site.

Publish a public extension

After you publish your extension as a private extension, you can update the visibility of the extension to make it public.

By default, the extension will be unlisted and accessible only through a link that you can share with your users. When you’re ready, you can submit it for listing in the extensions directory afterwards.

Warning

Once you make an extension public, it is not possible to change the visibility back to private.

As a Team Owner, to change your extension from private to public:

In the Netlify UI, select the Extensions tab for your team.
Select Created by your team.
Find your private extension in the list and select it.
On the extension’s details page, select Manage.
Under Visibility, select Change visibility.
Follow the prompts and confirm to change your extension’s visibility to public and unlisted.

Now that your extension is public, you can share the link to your extension with other Netlify users. After they log in to Netlify, they can learn about your extension and install it directly from the extension details page. The URL is formatted as https://app.netlify.com/extensions/[your-extension-slug].

You will notice the extension is labeled with a Unlisted badge instead of Private now.

To learn more about how users install and use extensions with Netlify sites, review the extensions and integrations section in the Netlify user docs.

Submit to the extensions directory

After you publish your extension as a public, unlisted extension, you can submit your extension for review and listing in the extensions directory.

Interested in publishing a partner extension?

If you’re interested in publishing your extension as a partner extension, contact the Netlify technology partner program before you submit and our team will work with you directly.

As a Team Owner:

In the Netlify UI, select the Extensions tab for your team.
Select Created by your team.
Find your extension in the list and select it.
On the extension’s details page, select Manage.
Under Visibility, select Submit for listing in the extensions directory.

Your extension must be public first

If the option to submit for listing doesn’t appear in the Netlify UI, make sure you complete the steps to publish your extension as a public, unlisted extension first.
Follow the prompts to submit your extension for review.

Once approved, your extension will be listed in the directory for users to find and install.

Got it!

Your feedback helps us improve our docs.