v1.5.0 to v2.0.0 Migration Guide
This guide covers migrating gatsby-theme-performance from v1.5.0 to v2.0.0. A major benefit to gatsby-theme-performance v2.0.0 is it now supports Gatsby 4!
v2.0.0 requires Gatsby 4. Gatsby 4 has a variety of performance improvements. You can read more about Gatsby 4 here.
Gatsby 4 requires using the new gatsby-plugin-image plugin instead of the deprecated gatsby-image plugin. Accordingly, v2.0.0 now requires gatsby-plugin-image. You can read more about gatsby-plugin-image here.
Note: The scope of this guide covers updating thegatsby-starter-performance codebase as-is. There may be issues outside the scope of this document based on the customizations you have made to your codebase.
1. Update dependencies
- Update @chordcommerce/gatsby-theme-performance to ^2.0.0
- Update gatsby to ^4.4.0
- Update theme-ui and gatsby-plugin-theme-ui to ^0.12.1
- Run yarn upgrade-interactive --latest to update all other dependencies to their latest. Note that the above dependencies should not be upgraded to their latest. Gatsby plugins should be updated to their latest so they are compatible with Gatsby 4. See Update Gatsby related packages for more information on updating Gatsby plugins.
Note: If you have installed Gatsby plugins other than the plugins in our Gatsby starter, this could introduce breaking changes that are not addressed in this guide. See Update Gatsby related packages for more information
2. Migrate to gatsby-plugin-image
Gatsby v4 uses the new gatsby-plugin-image instead of the deprecated gatsby-image. We need to remove gatsby-image and install gatsby-plugin-image, gatsby-plugin-sharp, and gatsby-transformer-sharp. See Migrating from gatsby-image to gatsby-plugin-image for a full overview of migrating to gatsby-plugin-image.
1. Remove gatsby-image
In version 1.5.0, gatsby-theme-performance included the gatsby-image package, however, this is no longer the case. If you have installed gatsby-image separately in your Gatsby project, you will need to remove it. If not, you can skip this step.
Run yarn remove gatsby-image.
2. Install gatsby-plugin-image and supporting packages
Run yarn add gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp.
3. Add gatsby-plugin-image to gatsby-config
Add gatsby-plugin-image plugins to gatsby-config.js. See Migrating from gatsby-image to gatsby-plugin-image for more information.
4. Run the codemod
Run npx gatsby-codemods gatsby-plugin-image src. to run the codemod which will update usage according to the new API. See Migrating from gatsby-image to gatsby-plugin-image for more information.
Note: the gatsby-plugin-image codemod removes the theme-ui JSX pragma (/** @jsx jsx */ at the top of the file), see theme-ui JSX pragma and ensure the JSX pragma is included in all theme-ui components.
Note: the gatsby-plugin-image codemod may add some undesirable code style changes. Be sure to check the diff before committing.
5. Manual gatsby-plugin-image migrations
As the codemod may not fix all gatsby-plugin-image issues, you will likely need to make some changes to ensure your codebase works with gatsby-plugin-image. See Migrating from gatsby-image to gatsby-plugin-image.
Contentful GraphQL query changes:
Since the codemod doesn’t apply to Contentful Gatsby Image queries, you will need to update them to work with gatsby-plugin-image. For example:
You can also update any queries to the file URL to use gatsby-plugin-image's getImage and getSrc helper functions. Be sure to replace all image.file.url or image.fluid.src use cases to prevent images from not rendering after the upgrade. For example:
See Migrating from gatsby-image to gatsby-plugin-image or the Gatsby Image Plugin Reference Guide for more information on the new Gatsby Image querying.
Congratulations! You’ve migrated to Gatsby 4! Be sure to run a gatsby clean before starting up your project to wipe the .cache and public folders.
See Common Errors below if you are getting any errors.
3. Upgrade from a gatsby-theme-performance version below v1.5.0
Please read the release notes for previous releases to find out what changed, but important breaking changes to highlight include:
Segment Consent Manager (breaking change in )
See the change to the Segment Consent Manager in v1.5.0 release notes and ensure you have the segmentConfig set in gatsby-config.js.
Product Merchant feed (breaking change in )
This theme no longer provides a Merchant feed. See the change in v1.2.0 release notes and implement a feed in your website code.
GraphQL: __typename field is no longer added automatically
As of Gatsby 3, __typename fields are no longer added automatically. So you may need to update your GraphQL queries and fragments to include __typename. This is usually used to render components based on GraphQL such as sections.
See here for more details.
Run gatsby clean
Be sure to run a gatsby clean before starting up your project to wipe the .cache and public folders.
Type with name "GatsbyImageLayout" does not exists'
This is likely because you didn't install gatsby-plugin-image. Also don't forget to include gatsby-plugin-image plugins in gatsby-config.
Plugin gatsby-plugin-gatsby-cloud is not compatible with your gatsby version.
If you are using gatsby-plugin-gatsby-cloud, chances are you are using version 1 due to compatability with Gatsby 2. Run yarn add gatsby-plugin-gatsby-cloud@latest to update to the latest.
Cannot read properties of undefined (reading 'initialized')
This is caused by not having segmentConfig set in gatsby-theme-performance plugin settings. As of version gatsby-theme-performance v1.5.0, segmentConfig is required. See v1.5.0 release notes.
Can't resolve 'react-hook-form'
In v2.0.0 we have removed the react-hook-form dependency so you will need to make sure you install it yourself. The previous version of gatsby-theme-autonomy used react-hook-form v5.7.2, so in order to prevent breaking changes, run yarn add email@example.com. You can also upgrade to the latest by following react-hook-form v5 to v6 Migration Guide and react-hook-form v6 to v7 Migration Guide.
theme-ui JSX pragma
Make sure you use the JSX pragma for theme-ui at the top of your file:
Failed to compile Gatsby Functions.
One possible cause of this error is the existence of a src/api directory in your site. Starting in Gatsby 3.7, the src/api directory is a reserved directory for Gatsby. Gatsby automatically maps files in this directory to function routes. If you were using the src/api directory prior to your upgrade, you'll need to rename the directory to stop Gatsby from publishing the contents as functions.