Migrating Source Plugins from v3 to v4

[meganesu]

Do you maintain a source plugin? Have questions or running into problems migrating from Gatsby 3 to Gatsby 4? Start a thread here, and someone from the Gatsby team will help you out!

[angeloashmore]

When running gatsby serve, the new query engine runs createSchemaCustomization with a subset of plugin options. If the plugin options includes functions, they are not included, similar to APIs in gatsby-browser.js.

Is this expected? If so, is there guidance on migrating function-reliant functionality?

gatsby-source-prismic uses the pluginOptionsSchema API to populate default function options. The relevant schema properties can be seen here: https://github.com/prismicio/prismic-gatsby/blob/bd62c0f431600a696c1f4ed70886675dc9e4bfbe/packages/gatsby-source-prismic/src/plugin-options-schema.ts#L209-L215

While default function options can be populated in the plugin's Node API implementation rather than in plugin option validation, functions provided by users cannot be.

[frederickfogerty]

Following up here, we're having the same issue - did you end up removing the functions from your schema @angeloashmore? How did you get around this?

@KyleAMathews does this function-pruning not happen with other APIs? Just with createSchemaCustomization?

[angeloashmore]

@frederickfogerty I removed default plugin option values that were functions. The default values for functions are populated in the Node APIs instead. I effectively needed to implement a “populateDefaultPluginOptions” function and call it within APIs like sourceNodes.

I’m not sure specifically which APIs are affected by this change but modifying the plugin option schema in this way requires all APIs to be adapted.

[frederickfogerty]

@angeloashmore I think I'm getting slightly confused by what "default plugin options" are - does this mean the default options values that can be overridden by a user? Because for the me the "overridden" values are not being passed through either.

What I'm thinking at the moment is that I need to restructure my plugin options to not include functions. Do you agree with this?

[angeloashmore]

@frederickfogerty Ah, I was under the impression that @imgix/gatsby used Gatsby's pluginOptionsSchema to populate default plugin options. With pluginOptionsSchema, plugins can define a Joi schema that validates options and assigns default values if needed. Gatsby 4's changes mean pluginOptionsSchema cannot assign default values if they are functions.

Since @imgix/gatsby is not using pluginOptionsSchema, fixing the problem will be different than what I described. The plugin needs to accept function plugin options as nullable (because they won't exist in Gatsby's build-only query server).

The validation schema (I think it's using io-ts?) needs to be changed for getURL and getURLs. It needs to accept undefined and handle it appropriately throughout the plugin.

It's worth noting that in gatsby-source-prismic, function plugin options are given generic default values. In the query server, the generic functions are used since the user-provided functions are no longer available. Depending on the plugin's functionality, you may not need the user-provided function in the query server.

[frederickfogerty]

@angeloashmore Thanks so much for following up here! I understand more now the differences between @imgix/gatsby's usage and other/normal usage.

My head is pretty out of Gatsby at the moment, and I haven't caught up on v4 - could you maybe explain or point me to where I can find out about the differences in the build stages? I couldn't find any information about the query engine or the render engines. For you, if you're using default function values, doesn't that mean that the app could potentially behave incorrectly during different parts of the build steps?

[ali-suhaib]

Hey guys , just upgrading to v4 from v3. It works fine in v3 but the source plugin gatsby-plugin-remote-images is not working in gatsby v4? Anyidea what should i do? I am creating remoteFile nodes for now in v4 and it works fine using develop but it is failing in build. Any suggestions what might replace gatsby-plugin-remote-images.