onPluginOptions lifecycle method

[ChristopherBiscardi]

Summary

Add a new onPluginOptions lifecycle method (or other way of controlling plugins) to allow singleton plugins to be used from multiple themes at the same time.

Basic example

One could imagine this implemented as a reduce call:

// gatsby-node in gatsby-plugin-mdx
exports.onPluginOptions = (mergedOptions, newOptions) => {
  return {
    ...mergedOptions,
    ...newOptions
  }
}

Motivation

Currently in Gatsby, if you include a plugin that expects to be the only instance (typically transformers like remark or mdx), you end up with multiple instances added and multiple non-especially-debuggable errors can pop up. Extending this to themes, it can make it harder to build composable themes (note the mdx option in official themes which allows you to turn an instance of mdx off or on).

[daaain]

Maybe a more flexible solution to this problem (without needing changes in existing plugins too) would be a generic way to extend the theme config by making the theme config object importable through some resolution?

See: #16593 (comment)

[pieh]

@daaain this is "good" escape hatch (good as in it will work) for users to work around lack of plugin merging options.

It still have some problem because just adding @narative/gatsby-theme-novela theme to gatsby config will result in multiple instances of gatsby-plugin-mdx which mean that building page will try to transform mdx multiple times (and last one - defined by user will "win"/overwrite previous work). Problem here is additional work / performance mostly.

I was recently chatting with @johno about this problem and maybe we could have nicer solution for escape hatch like that that would avoid double (or more) plugin instances by using something like "resolutions" in gatsby-config (inspired by yarn resolutions - https://classic.yarnpkg.com/en/docs/selective-version-resolutions/) where you could declare final shape of plugin options for some "problematic" plugins - in this case we would want to have single plugin instance with explicitely declared options.

This could unblock users while plugins implement onPluginOptions (or whatever final API for this feature would look like)

[daaain]

Ah I see, so while my solution does make it possible to have the "ultimate" merged config, it does not address the issue of the transformation now done multiple times. In fact, it makes it worse by adding one more instance...

That yarn inspired resolution could be the generic solution, or maybe a simpler one would be being able to somehow mark a plugin singleton in gatsby-config so that whatever you define would be the only instance used. And then you could maybe even choose to either have Gatsby merge all the configs or just take whatever you declare.