Gatsby: How to add a deprecation warning to a plugin?

[lightstrike]

I'd like to include some deprecation warnings in a PR I'm working on for gatsby-source-wordpress -- it seems like onPreInit could be a good place to check user-specified configuration options, but it's not clear to me if the config options are available to this step. How can I achieve something like the following:

const report = require(`gatsby-cli/lib/reporter`)

exports.onPreInit = async ( { userConfig } ) => {
  if (userConfig.useACF) {
    report.warn(
      `ACF functionality will be removed from gatsby-source-wordpress v4. Please migrate to gatsby-wordpress-acf.`
    )
  }
}  

[Chuloo]

Hi, @m-allanson is this something you can help with?

[m-allanson]

👍 @lightstrike, pluginOptions should get passed in as the second argument.

Here's an example from gatsby-transformer-screenshot that uses pluginOptions at the onPreBootstrap stage, which happens just after onPreInit:

https://github.com/gatsbyjs/gatsby/blob/bf3208ddc02c240302fff5b112343d715c69a0ca/packages/gatsby-transformer-screenshot/src/gatsby-node.js#L24-L27

There's a tutorial that runs through this in more detail at https://next.gatsbyjs.org/docs/source-plugin-tutorial/. I thought we had an issue for improving the API docs but having trouble finding it right now..

[lightstrike]

Thanks @m-allanson, confirming this works perfectly inside gatsby-node.js:

const report = require(`gatsby-cli/lib/reporter`)

exports.onPreBootstrap = ( {}, pluginOptions ) => {
  if (pluginOptions.useACF) {
    report.warn(
      `\n\nACF functionality will be removed from gatsby-source-wordpress v4. Please migrate to gatsby-wordpress-acf.\n\n`
    )
  }
}

I believe #4120 is the API docs issue, I've bookmarked this comment of yours about helper functions, which has been super helpful but should definitely find its way into docs someday :wink: