How to use Netlify build plugins

Introduction

When you deploy a site to Netlify, there is more happening than just running a build command and uploading files. Netlify runs a full build pipeline, and build plugins allow you to hook into that pipeline at specific moments.

Netlify build plugins let you run custom logic before, during, or after a build without maintaining your own CI infrastructure. They are ideal for tasks like validating content, generating files, uploading artifacts, or sending notifications.

In this guide, you'll learn what Netlify build plugins are, how they work, and how to use both community plugins and your own custom plugins.

What are Netlify build plugins

A Netlify build plugin is a Node-based script that runs during your site's build process.

Plugins can hook into lifecycle events such as:

• Before the build starts
• After the build completes
• When a build succeeds or fails
• While files are being generated

Unlike serverless functions, build plugins only run during deploys. They never run at request time and do not add runtime overhead to your site.

When to use build plugins

Build plugins are a good fit when you need to:

• Validate content before deploying
• Generate files during the build
• Upload artifacts to external services
• Modify or inspect the build output
• Send notifications after deploys

If you need logic that runs when a user visits your site, build plugins are not the right tool. In that case, you should look at serverless functions or edge functions instead.

Using a community build plugin

Netlify has a large ecosystem of prebuilt plugins you can use without writing any code.

Examples include:

• Lighthouse audits
• Sitemap generation
• Environment variable validation
• Asset optimization

Installing a plugin

Most plugins are installed using npm.

npm install --save-dev @netlify/plugin-lighthouse

Enabling the plugin

Once installed, you enable the plugin in your netlify.toml file.

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

That's all it takes. On the next deploy, Netlify will run the plugin automatically.

Understanding plugin lifecycle events

Each plugin can hook into one or more lifecycle events.

Some of the most common ones are:

• onPreBuild – runs before the build command
• onBuild – runs during the build
• onPostBuild – runs after the build completes
• onSuccess – runs after a successful deploy
• onError – runs if the build fails

Not all plugins use all hooks, but understanding them helps when you create your own.

Creating a custom Netlify build plugin

Sometimes you need behavior that no existing plugin provides. In that case, you can write your own.

Plugin file structure

A basic plugin consists of a JavaScript or TypeScript file that exports lifecycle hooks.

netlify-plugin-example/
  ├─ index.ts
  ├─ package.json

Basic plugin example

Here is a minimal example that logs a message after the build completes.

import type { NetlifyPlugin } from "@netlify/build"

const plugin: NetlifyPlugin = {
  onPostBuild() {
    console.log("Build finished successfully")
  },
}

export default plugin

Netlify automatically picks up this file when the plugin is referenced.

Registering a local plugin

You can reference a local plugin directly in netlify.toml.

[[plugins]]
  package = "./netlify-plugin-example"

This is useful when the plugin is specific to a single project.

Accessing build context and environment

Plugins receive contextual data from Netlify, including:

• Build directory paths
• Environment variables
• Deploy metadata
• Site configuration

For example:

onPreBuild({ utils, constants }) {
  console.log(constants.PUBLISH_DIR)
}

This makes it possible to write plugins that adapt to different deploy contexts such as previews or production.

Handling errors in plugins

If a plugin throws an error, the build will fail.

This can be intentional. For example, you might want to block a deploy if validation fails.

onPreBuild({ utils }) {
  utils.build.failBuild("Validation failed")
}

Failing fast like this helps prevent broken or incomplete deployments.

Common use cases for build plugins

Build plugins are commonly used for:

• Validating CMS content before deploy
• Checking required environment variables
• Generating sitemaps or RSS feeds
• Running audits and quality checks
• Uploading build artifacts
• Notifying external services

If something needs to happen every time your site builds, a build plugin is usually the cleanest solution.

Best practices

When working with Netlify build plugins:

• Keep plugins focused on a single responsibility
• Fail builds intentionally when correctness matters
• Avoid long-running tasks when possible
• Log clearly so failures are easy to diagnose
• Prefer community plugins before writing your own

Conclusion

Netlify build plugins give you powerful control over your deployment pipeline without leaving the Netlify ecosystem. They are easy to add, easy to maintain, and scale naturally with your site.

If you find yourself adding scripts to your build command or wiring external CI steps together, there is a good chance a build plugin can simplify your setup.