Netlify Build Plugins: changes to when `onSuccess` and `onEnd` are invoked during the build cycle

We’re making a change to how Netlify Build Plugins onSuccess and onEnd events work. The change will deploy sometime in January 2021, and we’ll post an update to this topic when it goes live.

Current: onSuccess and onEnd events occur after the build command is complete, but before any files are uploaded.
Upcoming: onSuccess and onEnd events occur after the site is deployed, live, and published to the deploy URL.
The purpose of the change is to support use cases like running audits on the live site by enabling plugin authors to run actions after the site is live.

What this means for plugin users
Plugins you’ve installed will run at the stages when they were intended to run! :tada: But this also requires a change in how your site’s build minutes are counted.

Build containers (and build minutes) run until completion of the build stage or until the last build plugin event finishes — whichever comes last. This means that when onSuccess and onEnd events are changed to occur later in the build-deploy lifecycle, more time will be counted in deploys with plugins that use those events.

To find out if plugins you’re using run during the onSuccess or onEnd events, check your deploy logs. Each event handler is identified in the log with a heading that follows the pattern:

{event name} command from {plugin name} 

Here is an example:

Unless you’re using the Algolia Crawler plugin (as noted below), these events are currently running before the log line that says, Starting to deploy site. After the change, they will run after the line that says, Site is live ✨.

Note: For sites using the Algolia Crawler plugin, listed in logs as @algolia/netlify-plugin-crawler, this new behavior has already been implemented, meaning that all onSuccess and onEnd events for that site occur after the deploy is live, as intended.

What this means for plugin authors
Currently, onSuccess and onEnd events run at essentially the same point in the build-deploy lifecycle as onPostBuild. When this change deploys in January, they’ll happen after the deploy and postprocessing stages instead. Here’s how to choose which event is right for your plugin:

  • If your plugin can work with built files that haven’t been deployed yet (for example, to scan for specific file content, or generate a sitemap), use onPostBuild. This allows the build container to stop running after your plugin finishes, before the site starts deploying.
  • If your plugin needs to work with deployed, live URLs (for example, to run live performance tests or crawl pages for search indexing), use onSuccess.
  • If your plugin needs to run after the deploy, regardless of whether it succeeds or fails (perhaps to send some monitoring stats to a third-party service), use onEnd.

You can update your plugin now to use the proper event handler, and it won’t cause any change to current behavior. Then after we deploy our changes in January, your plugin will start using the proper stage immediately.

4 Likes

This change has now been deployed! :tada:

3 Likes

We encountered an unexpected issue with this change, and have rolled back to the previous behavior for the duration of the weekend. We have a fix prepared and will update here on Monday.