chore(gatsby): output apis.json for current valid API list

[DSchau]

Description

This PR begins implementing one chunk of the work required to improve the experience outlined in #16055.

Specifically, this PR outputs an apis.json file that we can then distribute with NPM (and query with e.g. unpkg).

This uses a doclet @gatsbyVersion to denote when an API is available. This will be used to deliver richer error messages (or warnings) like so:

The plugin gatsby-source-filesystem is using the Gatsby API: `createSchemaCustomization`.

This API was introduced in gatsby@2.12.0. Upgrade your version of Gatsby (currently 2.1.0) for the best possible experience:

npm install gatsby@^2.12.0

A harder problem to solve is if we tweak an existing API (e.g. to pass a new utility or something) but I'd contend that we can either: 1) not solve that problem, or 2) Solve it later with additional metadata. As an example of this problem, createTypes was a new utility passed to sourceNodes in gatsby@2.2.0.

The idea is we'll progressively improve the error message when/if we add more metadata to apis.json in the future. For context, the below is a sample apis.json that will be produced with this PR.

{
  "ssr": {
    "replaceRenderer": {},
    "onRenderBody": {},
    "onPreRenderHTML": {},
    "wrapPageElement": {},
    "wrapRootElement": {}
  },
  "browser": {
    "onClientEntry": {},
    "onInitialClientRender": {},
    "onPreRouteUpdate": {},
    "onRouteUpdateDelayed": {},
    "onRouteUpdate": {},
    "shouldUpdateScroll": {},
    "registerServiceWorker": {},
    "replaceComponentRenderer": {
      "deprecated": true
    },
    "wrapPageElement": {},
    "wrapRootElement": {},
    "onPrefetchPathname": {},
    "onPostPrefetchPathname": {},
    "disableCorePrefetching": {},
    "replaceHydrateFunction": {},
    "onServiceWorkerInstalled": {},
    "onServiceWorkerUpdateFound": {},
    "onServiceWorkerUpdateReady": {},
    "onServiceWorkerActive": {},
    "onServiceWorkerRedundant": {}
  },
  "node": {
    "resolvableExtensions": {},
    "createPages": {},
    "createPagesStatefully": {},
    "sourceNodes": {},
    "onCreateNode": {},
    "onCreatePage": {},
    "setFieldsOnGraphQLNodeType": {},
    "createSchemaCustomization": {
      "version": "2.12.0"
    },
    "createResolvers": {
      "version": "2.2.0"
    },
    "preprocessSource": {},
    "generateSideEffects": {},
    "onCreateBabelConfig": {},
    "onCreateWebpackConfig": {},
    "onPreInit": {},
    "onPreBootstrap": {},
    "onPostBootstrap": {},
    "onPreBuild": {},
    "onPostBuild": {},
    "onPreExtractQueries": {},
    "onCreateDevServer": {}
  }
}

Any thoughts @gatsbyjs/core? Any metadata that is currently missing that we could use to improve this experience?

Related Issues

Begins implementing #16055.

[DSchau]

I have no idea why unit tests failed -- seems unrelated 😢

[pieh]

Adding documentation to gatsby's devDependencies seems to cause different node_modules structure (causing snapshot to differ).

I think this happens because we do already have documentation package in gatsby-transformer-documentation - but we use documentation@10, while this new package is documentation@12 so both can't be hoisted

---edit
in any case - snapshot testing those exact paths to node_modules seems fragile

[DSchau]

@pieh good catch -- it's fixed now.

Agreed, it's kinda why I've been leaning towards quite a bit less snapshots. They're kind of a fragile "easy" way to test things, when it seems better to perform tests on specific properties of the object's shape.

[DSchau]

Note: after changing documentation to 10.x, apis.json still has the same content (e.g. version for those few APIs, deprecated field for that one API, etc.).

[pieh]

I can't really figure out what this does - worth adding small note why this is here?

[DSchau]

Yeah -- this should block, good catch!

It's because of this line in gatsby-ssr.js, it's captured as an item in the output when it's not really an API.

/**
 * Object containing options defined in `gatsby-config.js`
 * @typedef {object} pluginOptions
 */

That creates:

{
  "namespace": "pluginOptions"
}

whereas every other one is an export so namespace is .replaceRenderer for instance.

[pieh]

Right, I now do remember I similar thing to our docs (just implemented differently):

gatsby/www/src/pages/docs/browser-apis.js

Lines 15 to 20 in aea3e39

	const funcs = sortBy(
	this.props.data.file.childrenDocumentationJs.filter(
	doc => doc.kind !== `typedef`
	),
	func => func.name
	)

(and I didn't add note on what it does and why it's there :S)

[pieh]

I think this is good to go. Left small question, but don't consider it blocker.

[DSchau]

Woo-hoo 🚀

https://unpkg.com/gatsby@2.13.41/apis.json