Netlify plugin

The build step, packaged as a Netlify Build Plugin. It runs after your build on the publish directory, using your site's Netlify URL.

npm i -D netlify-plugin-headlark

# netlify.toml
[[plugins]]
package = "netlify-plugin-headlark"

  # optional: fail the build if a page can't be optimized
  [plugins.inputs]
  strict = true

Add HEADLARK_KEY (your site's secret key) under Site configuration → Environment variables. Its scopes must include Builds; a variable scoped only to Functions or Runtime is invisible to the plugin.

What it does

• Runs on production deploys only (CONTEXT=production). Deploy previews and branch deploys are skipped, so they don't spend your plan's rewrites on unreleased content.
• Builds page URLs from your site's main address (Netlify's URL), so canonicals point at your live domain.
• Never fails a deploy unless strict = true. Without a key, or if Headlark can't reach the API, the pages deploy exactly as your build made them and the log says why.
• Uses the Headlark CLI it depends on; you don't need to install headlark separately.

The plugin is on npm as netlify-plugin-headlark.