v1.2.7 to v2.0.0 Migration Guide
This guide covers migrating gatsby-theme-autonomy from v1.2.7 to v2.0.0. A major benefit to gatsby-theme-autonomy 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-autonomy codebase as-is. There may be issues outside the scope of this document based on the customizations you have made to your codebase.
- Update @chordcommerce/gatsby-theme-autonomy to ^2.0.0
- Update @chordcommerce/chord-magic to ^1.1.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
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.
In version 1.2.7, gatsby-theme-autonomy 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.
Run yarn add gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp.
Add gatsby-plugin-image plugins to gatsby-config.js. See Migrating from gatsby-image to gatsby-plugin-image for more information.
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.
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:
Before:
After:
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:
Before:
GraphQL:
JSX:
After:
GraphQL:
JSX:
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.
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.2.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.0.6 release notes and implement a feed in your website code.
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.
Be sure to run a gatsby clean before starting up your project to wipe the .cache and public folders.
Error:
Solution:
This is likely because you didn't install gatsby-plugin-image. Also don't forget to include gatsby-plugin-image plugins in gatsby-config.
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.
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 react-hook-form@5.7.2. 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.
Error:
Solution:
Make sure you use the JSX pragma for theme-ui at the top of your file:
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.