We will soon lock plugin versions (#27), which means new ones will need to go through a PR and code review process.

We should document this in netlify/build and netlify/plugins README.md.

Any thoughts?

@verythorough @mheffner @erquhart

Every time a build has run, we collect, for each plugin, the following information in an anonymous way, as part of the plugin_runs API endpoint:

• name of the plugin
• version of the plugin
• whether the plugin has succeeded or failed (with a further distinction between cancelBuild vs failPlugin vs failBuild)

This information is very useful because it allows us to have precise information (per build, site or account) about:

• usage of each plugin
• error rate of each plugin
• whether some users got stuck on previous versions of specific plugins (when installed in their package.json)

There are some additional information that we are not sending but easily could:

• whether the plugin was installed through the UI, netlify.toml, netlify.toml combined with package.json, automatically installed, loaded from build image cache, etc.
• most used events by plugins

This in turns can be used in several ways:

• exposed to users to help them choose to use or not plugins: displayed in the UI, used to sort the plugins list, etc.
• internally to enrich our dashboards to get a good understanding of plugin usage, similar to https://cloud.us.humio.com/netlify-us-production/dashboards/JkRVXoKilcjr98MuMBZW9KPRakOXr4Mc

Since we already have this data, it might be interesting to discuss what can be done with it.

@verythorough @erquhart @seldo

Pending the upcoming change in onSuccess behaviour, we need to post it in the community.
Related to #134

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• chore(deps): update dependency dotenv to v16.4.5
• chore(deps): update dependency semver to v7.6.0
• chore(deps): update dependency husky to v9
• chore(deps): update dependency pacote to v18
• chore(deps): update dependency upper-case-first to v3

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update actions/checkout action to v4
• chore(deps): update actions/setup-node action to v4
• chore(deps): update dependency @sanity/client to v6
• chore(deps): update dependency ava to v6
• chore(deps): update dependency c8 to v9
• chore(deps): update dependency got to v14
• chore(deps): update dependency normalize-node-version to v14
• chore(deps): update dependency tsx to v4
• chore(deps): update googlecloudplatform/release-please-action action to v4
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

Incoming PR to publish the Essential Gatsby build plugin to the plugins page. V1 has just been published to NPM

Node.js is pretty good at abstracting platform-specific differences, but there are many ways to still write Build plugins that do not work (usually) on Windows.

Our production machines run on Ubuntu, but builds triggered through the Netlify CLI can be run on any machine. As many surveys show, a big proportion of developers are actually using Windows locally.

Should Build plugins be required to be cross-platform as part of our guidelines and enforced through code review?

We can use npm diffs to:

• ensure the version in the PR is actually published
• see the code differences between the current version and the proposed update version

Two solutions:

• Web based: https://diff.intrinsic.com/
• Programmatic: https://github.com/juliangruber/npm-diff

Two ways to do this:

• Easy/quick: add a "Diff" line to the issue template requesting an intrinsic diff link, Eg., https://diff.intrinsic.com/netlify-plugin-cypress/1.3.9/1.3.11
• Automated: use a GH check/app/etc to provide the link or diff when a PR is opened

Background at https://github.com/netlify/docs/issues/1064 and https://github.com/netlify/next-on-netlify-enterprise/issues/16

We should document the new compatibility field in this repository's Markdown documentation.

This field is currently used by our own plugins. Based on discussion about it with @verythorough, we should first wait a bit while we try this new field out before documenting it.

Previously it was not possible for plugins to add breaking changes. We have added a new compatibility field in plugins.json to support some specific (not all) types of breaking changes.

That field is optional. When present, it looks like this:

{
  "author": "netlify-labs",
  "description": "Automatically run a Lighthouse audit on your site after every build",
  "name": "Lighthouse",
  "package": "@netlify/plugin-lighthouse",
  "repo": "https://github.com/netlify-labs/netlify-plugin-lighthouse",
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "nodeVersion": "<12.13.0"
    }
  ]
}

In the above example: sites with a Node.js version below 12.13.0 will use @netlify/[email protected], while other sites will use @netlify/[email protected]. This applies to all sites, both new and existing ones, as soon as the PR in netlify/plugins is merged.

In other words, compatibility lists previous versions of a plugin for backward compatibility purpose. When no compatibility versions matches, the top-level version is used instead.

compatibility[*].version is an npm exact version, just like the top-level version.

The currently available condition properties are:

• nodeVersion (see example above), which checks against the site's Node.js version. Any semver ranges can be used.
• siteDependencies, which checks against the dependencies or devDependencies in the site's package.json. Any semver ranges can be used.

{
  ...
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "siteDependencies": { "next": "<=10.0.5" }
    }
  ]
}

When a site is using a plugin's compatibility version, a warning message is printed in the build logs, indicating that a new version of the plugin is available but that specific conditions must be matched in order to use it. For example, this would print something along the lines of "[email protected] is outdated: [email protected] is the latest version but this is incompatible with next <=10.0.5".

It is also possible to specify a migrationGuide URL which will be printed in that warning message.

{
  ...
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "siteDependencies": { "next": "<=10.0.5" },
      "migrationGuide": "https://github.com/netlify/netlify-plugin-example/MIGRATIONS.md#2.0.0"
    }
  ]
}

Clicking this button takes you to the repository for a Netlify build plugin and views the file README.md.

I noticed that clicking this button on one of my plugins has a 404 page from GitHub. I believe my filenames should not shout at me, and as such I don't have a README.md file, but rather a readme.md file.

It looks like the link is assuming that there is a README.md file, but you should probably be using the #readme element on all GitHub repositories:

-https://github.com/user/repo/blob/master/README.md
+https://github.com/user/repo#readme

Add authors to https://github.com/netlify/plugins/blob/master/plugins.json to avoid extract them from URL on the fly

This is an issue generated by (for-internal-use-only)github-tools

Description

This repository has exceeded the development grace period, and the repo owner must decide if branch protections should be enforced.
If this repository houses code used in production in any capacity, branch protections must be enforced. Read (for-internal-use-only)here for more details

What do I need to do?

• You can control whether or not branch protections are enforced by exclusively creating either of the labels:
  'enforce-branch-protections: true' or 'enforce-branch-protections: false'
• If there is no branch protection control label, this issue will be recreated.
• Once you have created either label, you can close this issue.
• If you have issues or questions, please reach out to #internal-security-n-compliance on slack.

The compatibility field was created to allow plugins to auto-upgrade breaking changes based on conditions such as Node.js version or Node modules versions. However, this will now also be used as part of versions pinning. In that new use case, no conditions is needed in the compatibility field, i.e. we should allow the items in that array have no conditions. At the moment, we validate against this.

Hi, I see your guidelines state that to update a plugin’s version, we need to have a successful build on Netlify.
That makes sense, but how can I make a build and test it with the new npm version?

I tried pushing the files to my personal website’s repository and used it like so:

[[plugins]]
  package = './netlify-plugin-inline-critical-css'

but it states that it cannot find the manifest.yml.

See those deploys:

• https://app.netlify.com/sites/tombonnike/deploys/5ece9676eb53de00061ebe09 (tried without a trailing slash)
• https://app.netlify.com/sites/tombonnike/deploys/5ece963f55c9c201e0d5b59c (with a trailing slash)

I double checked and the manifest is indeed present in the plugins/netlify-plugin-inline-critical-css folder: https://github.com/Tom-Bonnike/personal-website. (I tried putting the plugin under a plugins directory but it didn’t work either, updated my netlify.toml). See https://app.netlify.com/sites/tombonnike/deploys/5ece99c03ab1430006608bca

It would be great to have something like:

[[plugins]]
  package = 'netlify-plugin-inline-critical-css'
  version = '1.1.0' # Enforce npm version

To quickly be able to test plugins.

The plugins.json file syntax can be versioned, which allows renaming properties, for example (see this issue and this document.

The version is present in the URL, e.g. https://list-v1--netlify-plugins.netlify.app/plugins.json. However, it would be good to make it available in the plugins.json HTTP response as well.

At the moment, that file is a top-level array. Introducing that new field would require making it a top-level object instead. This would be a breaking change of the plugins.json syntax (see this) which would require updating every consumer.

Build plugins published to npm can use TypeScript by transpiling just before npm publish.

However, this does not work with local plugins. This is because plugins are imported at the beginning of the build. Since they might run before the build command, this cannot be used to transpile them.

We could fix this by:

• First detect whether the plugin is local and its main file's extension is .ts, .tsx, .cts or (once we support native ES modules) .mts.
• If so, then use ts-node/register or (once we support native ES modules) ts-node/esm
• Since each plugin has its own process, this will only apply on an individual plugin basis

@bengry What do you think?

@ehmicky has summarized common plugin issues in a separate issue comment. We can convert this information into a checklist of items needed before submitting a PR to add a plugin to the list.

We could add the content to the README (or contributor guide?), and could also benefit from putting the checklist into a PR template.

Auto-linting would be great, too, but until then, guidance works. :)

As netlify/build#1303, we would like to remove some deprecated syntax before GA, as a breaking change. I went through the list of plugins using those and made a list here. I have submitted a PR to each of those to fix each instance.

This means we probably should either:

• not make those breaking changes before GA
• temporarily disable those plugins until they merge those PRs and release a new version on npm

What are your thoughts?

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined

Add https://www.npmjs.com/package/@sdras/netlify-build-plugin-svgoptimizer when ready

Due to the compatibility field being used for version pinning and due to the fact that version pinning is major-version-based, the current algorithm requires each compatibility entry to have a different major version.

We should validate this as part on our existing automated tests.
Please note that, according to semver, the "major version" should be the second number for 0.*.* versions and the third number for 0.0.* versions.

Describe the bug
Prior to the merge of PR-119, I had installed [email protected] via the Netlify UI. I removed from the UI to create the new version 1.1.0 locally. Now that the PR has been merged, when I re-add the plugin via the Netlify UI, the logs show the buildbot trying to deploy the old version.

To Reproduce

1. Install a plugin via Netlify UI
2. Successfully Re-deploy site with plugin
3. Remove the plugin from your site via Netlify UI
4. Update the plugin to a new version and deploy version change to netlify/plugins/plugins.json
5. Re-install the plugin via Netlify UI
6. Attempt to Re-deploy site with plugin
7. Note in build log that buildbot attempted to deploy old version of plugin

Expected behavior

• In this specific scenario, buildbot should detect that the plugin cache is stale and deploy new version.
• If it doesn't already exist, In the scenario where an already-installed plugin has been updated to a newer version, the Netlify UI should provide the user a collection of calls to action to minimally give them the option to stay on current version or upgrade to newer version with follow up calls to action to either deploy now or later.

Evidence
buildbot deploying cached version of plugin: duvee-digital-team Build 5f1581769bd3240008f69ea9

Raised from an internal Slack conversation:
https://netlify.slack.com/archives/C012GT6MYKU/p1611611766161400

Some of our plugins have names ending with plugin which leads to this message when installing them:

One plugin has plugin in the middle:

Some plugins have title case naming:

Some don't:

We should have a consistent naming convention, thoughts?

The full background of the discussion is here.

onPostBuild happens before deploy, and can prevent a build from being deployed.
onSuccess happens after deploy, and cannot prevent a build from being deployed.

We should send PRs to migrate plugins that either:

• use onPostBuild, but the logic should happen after deploy
• use onEnd, but errors should prevent a build from being deployed

After this is done, we should also send PRs to migrate plugins that use utils.build.failBuild() or utils.build.cancelBuild() within onSuccess, onEnd or onError.

We have a bunch of plugins that are starting some kind of site audit (on the live site) in onSuccess.
Some of them only run in production context and some of them will also run on deploy previews (but audit the live site).

We need to look into how plugins are handling deploy context and also how URL, DEPLOY_URL, DEPLOY_PRIME_URL envs are used.

Some plugins are assuming onSuccess happens after the site is live (which will be soon hopefully), which adds to the confusion.

Examples:
https://github.com/tkadlec/netlify-build-plugin-speedcurve/blob/0a54471574481fcca947fe356bab32ea190fae31/index.js#L18

https://github.com/PerfBeacon/netlify-build-plugin-perfbeacon/blob/84795d829048166c464d181fba0e2a359cc172c0/index.js#L20

https://github.com/borisschapira/netlify-build-plugin-dareboost/blob/1b191b9f3c887c9feec45ba6ea3cae84439e6394/index.js#L79

https://github.com/cdeleeuwe/netlify-plugin-submit-sitemap/blob/629df29da1a3c29528d31480abd00947735714fa/index.js#L67

https://github.com/DebugBear/netlify-build-plugin-debugbear/blob/c3855d63e471b12013694de6f8a8e85207e2e3e8/index.js#L45

Add featured to https://github.com/netlify/plugins/blob/master/plugins.json

Performance testing plugin using k6 https://github.com/loadimpact/k6

See https://k6.io/ for how it works

import http from 'k6/http';
import {check, sleep} from 'k6';

export default function() {
  const data = {username: 'username', password: 'password'};
  let res = http.post('https://netlifysite.com.com/.functions/foo', data);
    check(res, { 'success login': (r) => r.status === 200 });
    sleep(0.3);
}

Some plugins fail UI installation since the have required inputs:

 - netlify-plugin-brand-guardian
 - netlify-plugin-rss
 - netlify-plugin-add-instagram

We should remove them as they fail the build immediately when installed from UI.

This is only a partial list

The list of plugins in plugins.json populates the list of plugins in the Netlify UI. Sometimes, plugins will have to be removed, for example, if the plugin stops working, stops meeting the guidelines (#20), or is unpublished from npm.

We could just remove the plugin from the json list, but there are instances where we might still want information about the plugin available - for example, to display currently installed plugins in the UI.

One way to do this would be to add an "active": false field to an inactive plugin. (I'd say "inactive": true, but I hesitate because double negatives can be tricky.) When a plugin has that field, I think we might also want to:

• Change the name to Some Plugin Name (inactive), so another author might be able to add a new plugin called Some Plugin Name.
• Remove the repo URL, or account for the fact that it may no longer exist or be useful.
• Change or remove other fields?

Thoughts? cc @erquhart @nasivuela @charliegerard @ehmicky

It will soon be possible for plugins to modify netlifyConfig.* properties (issue at netlify/build#1193).

However, we should make sure plugins do so while still allowing users to override that behavior, unless there is a good reason not to. For example, instead of overriding the build command, plugins should consider appending to it instead.

Support generating the exposed content via endpoints based on this spec

@netlify/ecosystem-pod-integrations

This repository does not use our common Node.js setup, including @netlify/eslint-config. We should set this up.