feat: add unstable_onPluginInit that would execute once in all processes (#31901)

* feat: add unstable_onPluginInit that would execute once in all processes

* update tests

* add basic unit test for isGatsbyNodeLifecycleSupported

* add readme section about added lifecycle existance check

* don't mix ESM and CJS in readme

* add example to node api docs

* set version to 3.9

* try/catch lifecycle check, just to make sure we never crash because of it

* uncoditionally set actions and plugins in onPreBootstrap, it doesn't hurt to do so

Author: pieh

examples/using-redux-w-interaction-code-splitting/static/background.svg

@@ -13,6 +13,7 @@
     "filenamify": "^4.2.0",
     "fs-extra": "^9.1.0",
     "gatsby-core-utils": "^2.9.0-next.0",
+    "gatsby-plugin-utils": "^1.9.0-next.0",
     "gatsby-telemetry": "^2.9.0-next.0",
     "got": "^10.7.0",
     "imagemin": "^7.0.1",
@@ -34,8 +35,7 @@
     "@types/sharp": "^0.27.1",
     "babel-preset-gatsby-package": "^1.9.0-next.0",
     "cross-env": "^7.0.3",
-    "gatsby-plugin-image": "^1.9.0-next.0",
-    "gatsby-plugin-utils": "^1.9.0-next.0"
+    "gatsby-plugin-image": "^1.9.0-next.0"
   },
   "homepage": "https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp#readme",
   "keywords": [

examples/using-redux-w-page-code-splitting/static/background.svg

@@ -11,6 +11,16 @@ const { slash } = require(`gatsby-core-utils`)
 const { setPluginOptions } = require(`./plugin-options`)
 const path = require(`path`)
 
+let coreSupportsOnPluginInit
+try {
+  const { isGatsbyNodeLifecycleSupported } = require(`gatsby-plugin-utils`)
+  coreSupportsOnPluginInit = isGatsbyNodeLifecycleSupported(
+    `unstable_onPluginInit`
+  )
+} catch (e) {
+  coreSupportsOnPluginInit = false
+}
+
 exports.onCreateDevServer = async ({ app, cache, reporter }) => {
   if (!_lazyJobsEnabled()) {
     return
@@ -104,6 +114,14 @@ exports.onPostBootstrap = async ({ reporter, cache, store }) => {
   }
 }
 
+if (coreSupportsOnPluginInit) {
+  // to properly initialize plugin in worker (`onPreBootstrap` won't run in workers)
+  exports.unstable_onPluginInit = async ({ actions }, pluginOptions) => {
+    setActions(actions)
+    setPluginOptions(pluginOptions)
+  }
+}
+
 exports.onPreBootstrap = async ({ actions, emitter, cache }, pluginOptions) => {
   setActions(actions)
   setPluginOptions(pluginOptions)

packages/gatsby-plugin-sharp/package.json

@@ -44,3 +44,22 @@ it(`should partially validate one value of a schema`, async () => {
   expect(errors).toEqual([`"toVerify" must be a boolean`])
 })
 ```
+
+### `isGatsbyNodeLifecycleSupported`
+
+Utility to be used by plugins to do runtime check against `gatsby` core package checking wether particular `gatsby-node` lifecycle API is supported. Useful for plugins to be able to support multiple `gatsby` core versions.
+
+#### Example
+
+```js
+const { isGatsbyNodeLifecycleSupported } = require(`gatsby-plugin-utils`)
+
+// only use createSchemaCustomization lifecycle only when it's available.
+if (isGatsbyNodeLifecycleSupported(`createSchemaCustomization`)) {
+  exports.createSchemaCustomization = function createSchemaCustomization({
+    actions,
+  }) {
+    // customize schema
+  }
+}
+```

packages/gatsby-plugin-sharp/src/gatsby-node.js

@@ -0,0 +1,13 @@
+import { isGatsbyNodeLifecycleSupported } from "../node-api-is-supported"
+
+describe(`isGatsbyNodeLifecycleSupported`, () => {
+  it(`returns true for supported API (createSchemaCustomization)`, () => {
+    expect(isGatsbyNodeLifecycleSupported(`createSchemaCustomization`)).toEqual(
+      true
+    )
+  })
+
+  it(`returns false for unsupported API (thisIsNotSupported)`, () => {
+    expect(isGatsbyNodeLifecycleSupported(`thisIsNotSupported`)).toEqual(false)
+  })
+})

packages/gatsby-plugin-utils/README.md

@@ -1,3 +1,4 @@
 export * from "./validate"
 export * from "./test-plugin-options-schema"
 export * from "./joi"
+export * from "./node-api-is-supported"

packages/gatsby-plugin-utils/src/__tests__/node-api-is-supported.ts

@@ -0,0 +1,12 @@
+export function isGatsbyNodeLifecycleSupported(apiName: string): boolean {
+  let availableAPIs
+  try {
+    availableAPIs = require(`gatsby/apis.json`)
+  } catch (e) {
+    throw new Error(
+      `Couldn't check available APIs. Make sure you are on gatsby version >=2.13.41`
+    )
+  }
+
+  return !!availableAPIs?.node?.[apiName]
+}

packages/gatsby-plugin-utils/src/index.ts

@@ -57,6 +57,9 @@ it("generates the expected api output", done => {
           "resolvableExtensions": Object {},
           "setFieldsOnGraphQLNodeType": Object {},
           "sourceNodes": Object {},
+          "unstable_onPluginInit": Object {
+            "version": "3.9.0",
+          },
           "unstable_shouldOnCreateNode": Object {
             "version": "2.24.80",
           },

packages/gatsby-plugin-utils/src/node-api-is-supported.ts

@@ -13,6 +13,7 @@ import {
   ICurrentAPIs,
   validateConfigPluginsOptions,
 } from "./validate"
+import apiRunnerNode from "../../utils/api-runner-node"
 import {
   IPluginInfo,
   IFlattenedPlugin,
@@ -124,5 +125,8 @@ export async function loadPlugins(
     payload: flattenedPlugins,
   })
 
+  // And let plugins initialize if they want to
+  await apiRunnerNode(`unstable_onPluginInit`)
+
   return flattenedPlugins
 }

packages/gatsby/scripts/__tests__/api.js

@@ -410,6 +410,20 @@ export const onCreateWebpackConfig = true
  */
 export const onPreInit = true
 
+/**
+ * Lifecycle executed in each process (one time per process). Used to store actions etc for later use.
+ *
+ * @example
+ * let createJobV2
+ * exports.unstable_onPluginInit = ({ actions }) => {
+ *   // store job creation action to use it later
+ *   createJobV2 = actions.createJobV2
+ * }
+ * @gatsbyVersion 3.9.0
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const unstable_onPluginInit = true
+
 /**
  * Called once Gatsby has initialized itself and is ready to bootstrap your site.
  */