Upgrading my Gatsby themes to Gatsby v3

Thilo Maier •
Last modified:

Gatsby v3 was launched today at Gatsby Conf. The two features that stood out to me were incremental builds and fast refresh. Both features should result in a better DX for consumers of my Gatsby themes. So I gave it a try and upgraded my themes.

My starting point was the migration guide from v2 to v3. I started by upgrading Gatsby to v3 for the two example sites with which I develop my themes in this monorepo. I ran

yarn workspace core-themes-example dev

and saw this:

$ gatsby develop
/home/node/workspace/gatsby-themes/node_modules/gatsby-recipes/node_modules/graphql-compose/lib/utils/toInputType.js:100
        throw new Error(`${`Can not convert field '${tc.getTypeName()}.${fieldName}' to InputType` + '\nIt should be ObjectType or InterfaceType, but
got \n'}${(0, _misc.inspect)(fc.type)}`);
        ^

Error: Can not convert field 'GatsbyPlugin.options' to InputType
...

OK, a long shot to hope that upgrading to Gatsby v3 without upgrading any plugins does not break anything. I ran

yarn outdated

which showed me a long list of plugins that needed to be upgraded:

yarn outdated v1.22.5
Package                    Current       Wanted                 Latest Workspace                              Package Type    URL
@theme-ui/prism            0.6.0-alpha.7 0.6.0-canary.c5a716a.0 0.3.5  @maiertech/gatsby-theme-theme-ui       dependencies    https://github.com/system-ui/theme-ui#readme
gatsby-plugin-catch-links  2.10.0        2.10.0                 3.0.0  @maiertech/gatsby-theme-theme-ui       dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-catch-links#readme
gatsby-plugin-image        0.7.1         0.7.2                  1.0.0  @maiertech/gatsby-theme-digital-garden dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-image#readme
gatsby-plugin-mdx          1.10.0        1.10.1                 2.0.0  core-themes-example                    dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx#readme
gatsby-plugin-mdx          1.10.0        1.10.1                 2.0.0  @maiertech/gatsby-theme-digital-garden dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx#readme
gatsby-plugin-mdx          1.10.0        1.10.1                 2.0.0  @maiertech/gatsby-theme-pages-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx#readme
gatsby-plugin-mdx          1.10.0        1.10.1                 2.0.0  @maiertech/gatsby-theme-posts-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx#readme
gatsby-plugin-react-helmet 3.10.0        3.10.0                 4.0.0  @maiertech/gatsby-theme-base           dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-react-helmet#readme
gatsby-plugin-sharp        2.14.3        2.14.3                 3.0.0  @maiertech/gatsby-theme-pages-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp#readme
gatsby-plugin-sharp        2.14.3        2.14.3                 3.0.0  @maiertech/gatsby-theme-posts-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp#readme
gatsby-plugin-sitemap      2.12.0        2.12.0                 3.0.0  @maiertech/gatsby-theme-digital-garden dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sitemap#readme
gatsby-plugin-theme-ui     0.6.0-alpha.7 0.6.0-canary.c5a716a.0 0.3.5  @maiertech/gatsby-theme-theme-ui       dependencies    https://github.com/system-ui/theme-ui#readme
gatsby-source-filesystem   2.11.0        2.11.1                 3.0.0  @maiertech/gatsby-theme-pages-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-filesystem#readme
gatsby-source-filesystem   2.11.0        2.11.1                 3.0.0  @maiertech/gatsby-theme-posts-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-filesystem#readme
gatsby-transformer-sharp   2.12.0        2.12.0                 3.0.0  @maiertech/gatsby-theme-pages-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-sharp#readme
gatsby-transformer-sharp   2.12.0        2.12.0                 3.0.0  @maiertech/gatsby-theme-posts-core     dependencies    https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-sharp#readme
theme-ui                   0.6.0-alpha.7 0.6.0-canary.c5a716a.0 0.3.5  @maiertech/gatsby-theme-theme-ui       dependencies    https://github.com/system-ui/theme-ui#readme
Done in 0.90s.

I upgraded all plugins with a major version change and my site launched without errors:

You can now view coding-garden in the browser.
⠀
  http://localhost:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema
⠀
  http://localhost:8000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build

This is quite impressive for a major version upgrade. Nothing broke in both example sites. But there were a ton of warnings. But this was expected after skimming over the migration guide. I tackled all warnings one by one, starting with this type of warning:

warn Plugin @maiertech/gatsby-theme-posts-core is not compatible with your gatsby version 3.0.0 - It requires gatsby@^2.24.77

As mentioned in the migration guide section “For Plugin Maintainers”, gatsby in peerDependencies needs to be bumped to v3 for all plugins (and themes):

"peerDependencies": {
  "gatsby": "^3.0.0",
  "react": "^16.14.0 || ^17.0.1",
  "react-dom": "^16.14.0 || ^17.0.1"
},

First warning eliminated. The next type of warning was a deprecation warning:

warn Deprecation warning: `@nodeInterface` extension is deprecated and will be removed in Gatsby v4. Use interface inheritance instead.
To upgrade replace the old format:
  interface `Page` @nodeInterface
with the new one (in `createTypes` action of schema customization API):
  interface `Page` implements Node
Read more about schema customization here:
https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/

Gatsby v3 does not just pull the rug from under your feet and eliminate APIs. Instead, it offers a transition period until the release of Gatsby v4 for legacy APIs to be phased out. Migration guide section @nodeInterface details this warning. I went ahead and eliminated all occurrences of @nodeInterface as explained in the guide. Second warning eliminated.

The next error was triggered by Webpack, which complained that I was trying to use path from Node’s API in the browser during development:

ERROR #98124  WEBPACK

Generating development JavaScript bundle failed

Can't resolve 'path' in '/home/node/workspace/gatsby-themes/packages/gatsby-helpers'

If you're trying to use a package make sure that 'path' is installed. If you're trying to use a local file make sure that the path is correct.

BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "path": require.resolve("path-browserify") }'
        - install 'path-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "path": false }

File: ../../packages/gatsby-helpers/index.js:12:16

This error is shown because I use @maiertech/gatsby-helpers, in which some helper functions use the Node API. One of them, createPath, uses Node’s path and runs in one example site in the browser during development. The solution to eliminating this error is outlined in the above error message and the migration guide section about Webpack 5 config tells you how to load a polyfill:

module.exports.onCreateWebpackConfig = ({ actions }) => {
	actions.setWebpackConfig({
		resolve: {
			alias: {
				path: require.resolve('path-browserify')
			},
			fallback: { fs: false }
		}
	});
};

Using a polyfill is not ideal, but it did trick and eliminated the error. The next warning was specific to one of my themes, which wires up Theme UI:

warn Plugin gatsby-plugin-theme-ui is not compatible with your gatsby version 3.0.0 - It requires gatsby@^2.13.1

gatsby-plugin-theme-ui’s peerDependencies have not yet been upgraded to Gatsby v3. Following the advice in migration guide section “Handling dependencies for plugins that are not yet updated” I had not much choice other than ignoring the warning since gatsby-plugin-theme-ui is outside my control. Since the plugin works fine with Gatsby v3, not a deal-breaker.

Then I released new versions for all my themes and upgraded my digital garden to Gatsby v3 and the latest @maiertech/gatsby-theme-digital-garden, which I had just released. But I ran into another error:

yarn run v1.22.5
$ gatsby develop

 ERROR

Unexpected key "pageData" found in preloadedState argument passed to createStore. Expected to find one of the known reducer keys instead: "nodes",
"logs", "pages", "redirects", "schema", "definitions", "staticQueryComponents", "status", "webpack", "webpackCompilationHash", "config", "lastAction",
"jobsV2", "pageDataStats", "components", "babelrc", "jobs", "nodesByType", "program", "resolvedNodesCache", "nodesTouched", "flattenedPlugins",
"pendingPageDataWrites", "schemaCustomization", "inferenceMetadata", "staticQueriesByTemplate", "queries", "visitedPages", "html". Unexpected keys will
be ignored.

This looked very much like a cache problem and one

yarn clean

later, the upgrade to Gatsby v3 was complete.

I think the Gatsby team did a great job with the v2 to v3 migration guide because it covered everything I needed to know for the upgrade. For a normal Gatsby site that uses no theme or one of the official themes, I would expect that upgrading to Gatsby v3 should work without any issues.