Check for incompatible Gatsby plugins

[m-allanson]

Summary

It can be confusing to work out which version of a plugin to use with your version of Gatsby, particularly when trying out pre-release versions. Gatsby should show a warning if it knows that your plugins are incompatible.

Setting a version to ^1.0.0 won't install pre-release versions like 2.0.0-beta.2.

Basic example

The following setup will install a beta version of Gatsby v2, but only version 1 of gatsby-plugin-foo, as the ^ version range character won't select the pre-release version of the foo plugin.

npm dist-tags ls gatsby
latest: 1.9.277
next: 2.0.0-beta.85

npm dist-tags ls gatsby-plugin-foo
latest: 1.0.0
next: 2.0.0-beta.2

package.json (excerpt)

// ...
  "dependencies": {
    "gatsby": "next",
    "gatsby-plugin-foo": "^1.0.0",
    "gatsby-plugin-react-helmet": "next",
// ...

gatsby-config.js

module.exports = {
  plugins: [
    'gatsby-plugin-react-helmet', 
    `gatsby-plugin-foo`
  ],
}

gatsby-plugin-foo's most recent package.json

  "version": "2.0.0-beta.2",
  "peerDependencies": {
    "gatsby": ">2.0.0-alpha"
  },

gatsby-plugin-foo v1's package.json

  "version": "1.0.4",
  "peerDependencies": {
    "gatsby": "1.x"
  },

Gatsby could be updated to check the peerDependencies of installed plugins that are listed in your project's gatsby-config.js. It could display a warning if they don't match.

This would be similar to npm / yarn's peerDependency warnings - but can be displayed in the Gatsby CLI and could contain more specific info related to Gatsby.

Motivation

This makes it easier to use pre-release versions of Gatsby by avoiding mysterious errors that occur from using incompatible plugins.

This issue might not be such a problem once Gatsby 2.0.0 is released, so it may not be worth spending the time building this feature.

[m-allanson]

A first step towards this would be to encourage plugin authors to specify a peerDependencies section of their plugin's package.json file:

"peerDependencies": {
    "gatsby": "supported version range goes here"
  },

We could start with updating the docs to mention this, and updating the official Gatsby plugins to do this.

[KyleAMathews]

We should add to the migration guide for plugins. If it turns out your plugin isn't compatible, the very first thing you do is add peerDependency saying that and release that so people will know and then make a new major release with the changes

[m-allanson]

This could be useful: https://github.com/npm/node-semver