Build Plugins

Netlify Build Plugins extend the functionality of the Netlify Build process. You can install plugins made by others, or write your own. You can save them locally in your repository, or share them with others using npm and the Netlify plugins directory.

Build Plugins expand what your Netlify builds are capable of. For example, you can use plugins to:

  • speed up builds by optimizing and debugging your build cache
  • import and convert data from external sources
  • check for broken links in a site after building
  • analyze and optimize site asset handling for better runtime performance
  • generate content like sitemaps, RSS feeds, and search indexes

# Install a plugin

To get a sampling of what plugins can do, visit the Build Plugins product page or the in-app plugins directory. All plugins listed on those pages can be installed directly from the Netlify UI. They can also be installed using the Netlify configuration file, which allows more configuration options and a broader selection of plugins.

# UI installation

To install plugins using the Netlify UI, select the Plugins tab from any team-level page or follow this direct link to the plugins directory.

Consider the context

UI-installed plugins run in all deploy contexts. To limit the context for the plugin, use file-based installation instead.

The Options menu in each plugin listing includes links to the plugin docs, npm package profile, and issue tracker. You can use this information to decide if the plugin is right for your site. When you’re ready to install the plugin, select Install. This will direct you to a site selection screen.

Current or new build image required

Build Plugins are not available on the legacy Ubuntu Trusty 14.04 build image. To update your site build image, go to Site settings > Build & deploy > Continuous deployment > Build image selection > Edit settings, and select Ubuntu Xenial 16.04 or Ubuntu Focal 20.04.

You can use the search box to find sites across all of your teams.

To run a build with your new plugin, you can visit the site Deploys tab and select Trigger deploy.

# Required environment variables

Though most plugins that can be installed using the Netlify UI require no configuration for default operation, some may require you to set one or more build environment variables. Refer to the plugin’s documentation, linked from the Options menu for the plugin listing in the Netlify UI, for details.

# File-based installation

File-based plugin installation allows advanced plugin configuration and a wider selection of plugins than those available in the UI.

You can use file-based installation for either of the following:

  • installing local plugins that you write and store in your repository
  • accessing a wide selection of plugins published by the community on npm, some of which aren’t available in the plugins directory

In both cases, you configure settings in netlify.toml. For a plugin published to npm, you also add it as a dependency. Then you can test or run the plugin as part of a build.

# Configure settings

To tell Netlify to run a plugin during your build, add it to a Netlify configuration file stored in your site’s base directory. A plugin configured globally with [[plugins]] runs in all deploy contexts, but you can also configure a plugin by deploy context.

Here’s a sample configuration with two plugins installed in all deploy contexts.

# Configuration for a plugin published to npm
[[plugins]]
package = "netlify-plugin-replace-images-with-kittens"

  [plugins.inputs]
  colors = ["orange tabby", "black with socks"]

# Configuration for a local plugin
[[plugins]]
package = "/plugins/netlify-plugin-moar-kittens"

Each [[plugins]] entry accepts two keys:

  • package (required):
    • For a plugin installed from npm, the npm package name of the plugin.
    • For a local plugin, the path to a directory containing the plugin’s index.js and manifest.yml files. The package value for a local plugin must start with . or /.
  • inputs: Custom settings that the plugin author may specify as required or available for configuring the plugin. To specify inputs per deploy context, refer to configure by deploy context.

For npm-published plugins, you can find these details in each plugin’s package documentation on the npm Public Registry.

Sometimes order matters

Different plugins run during different stages of your build. When multiple plugins are set to run in the same stage, they will run in the order they are listed in the Netlify configuration file. An npm-published plugin’s README should indicate if order is important to that plugin’s functionality.

# Configure by deploy context

Using specific settings in your Netlify configuration file, you can limit a Build Plugin to run in a certain deploy context only, or you can configure a plugin’s inputs settings differently per context.

Here’s an example configuration that runs the Sitemap plugin in the context of production deploys only.

# Use double brackets since `plugins` is an array of tables.
[[context.production.plugins]]
package = "@netlify/plugin-sitemap"

And here’s an example configuration that runs the Cypress plugin differently based on deploy contexts.

# Use Cypress plugin for this site.
# This section, by itself, configures the plugin
# for all deploy contexts (production, branch deploys, Deploy Previews).
[[plugins]]
package = "netlify-plugin-cypress"
  [plugins.inputs]
  record = true

# Don’t record Cypress tests in Deploy Previews.
# Since this entry is more specific, it overrides the entry above.
# `context.deploy-preview.plugins` and `package` must be included.
[[context.deploy-preview.plugins]]
package = "netlify-plugin-cypress"
  # Use single brackets since `inputs` is an object property
  [context.deploy-preview.plugins.inputs]
  record = false

This configuration records test results and artifacts on the Cypress Dashboard for production and branch deploys only, not Deploy Previews.

UI-installed plugins run on all contexts

To limit a plugin to certain deploy contexts, ensure that you’ve configured the plugin for your site using file-based installation only and not UI installation from the plugins directory.

# Next steps

If you’re installing a local plugin, you can run and test it after configuration. Otherwise, you'll add a dependency to package.json.

# Add dependency

For a plugin from npm, there’s an additional step beyond editing the Netlify configuration file. You must use npm, yarn, or another Node.js package manager to add the plugin to devDependencies in your site’s package.json.

Evaluate the plugin code

Plugins outside of the Netlify plugins directory have not been reviewed or approved by Netlify staff. Review plugin code for security concerns before installing.

From your project’s base directory, use a command like this to add the dependency:

    npm install -D netlify-plugin-replace-images-with-kittens
    
    yarn add -D netlify-plugin-replace-images-with-kittens
    
    // Make sure to add code blocks to your code group

    # Run and test

    When you save your changes to your repository and push them to your Git provider, the build that’s triggered on Netlify will run with plugins installed for that deploy context. If you would like to test a plugin before running it in a production build, you can use a branch deploy or Deploy Preview, or you can run the build locally with Netlify CLI.

    # Remove a plugin

    The steps for removing a plugin depend on how the plugin was installed.

    For plugins installed in the UI, find the plugin entry on the site’s Plugins page. (Note this is not the same as the plugins directory which is linked at the team level.) In the plugin’s Options menu, select Uninstall. Subsequent builds will not use the uninstalled plugin.

    For plugins installed through file-based installation, delete or comment out the plugin’s configuration fields from your Netlify configuration file. When you push your committed changes, the resulting build will run without the plugin. If you’re removing an npm-published plugin and want to avoid installing code you won’t use, you can uninstall the plugin package using npm.

    # Create a plugin

    Once you’ve had a chance to try out some community-built plugins, you may want to make one of your own. To learn how, visit the create plugins doc.

    # Get help

    Netlify Build Plugins are created by developers at Netlify and in the community. If you need help with a plugin, contact the plugin author by submitting an issue on the plugin repository. For plugins in the Netlify UI, you can find a link to the plugin issues under the Options menu for the plugin listing. If a plugin author doesn’t respond to an issue within a week, you can request deactivation of the plugin from the Netlify UI.

    For more general questions, or to discuss Build Plugins with other members of the community, visit the Netlify Support Forums.

    # More Build Plugins resources