v1.2.7 to v2.0.0 Migration Guide
This guide is to help users of Chord gatsby-theme-autonomy migrate from v1.2.7 to v2.0.0.

Overview

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!

Major Changes:

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-plugin-image

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.

Reading

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. If you are having issues, please be sure to take a look at the Gatsby migration guides.

Upgrade Guide

1. Update Dependencies

  1. 1.
    Update @chordcommerce/gatsby-theme-autonomy to ^2.0.0
  2. 2.
    Update @chordcommerce/chord-magic to ^1.1.0
  3. 3.
    Update gatsby to ^4.4.0
  4. 4.
    Update theme-ui and gatsby-plugin-theme-ui to ^0.12.1
  5. 5.
    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 if it is installed

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.

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.
module.exports = {
plugins: [
// ...
'gatsby-plugin-image',
'gatsby-plugin-sharp',
'gatsby-transformer-sharp',
// ...
],
}

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 gatsby-plugin-image 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:

Queries

Before:
fluid(maxWidth: 500, quality: 80) {
...GatsbyContentfulFluid_withWebp
}
After:
gatsbyImageData(
quality: 80
layout: CONSTRAINED
width: 500
)

Helpers

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:
image {
title
fluid(maxWidth: 500, quality: 80) {
...GatsbyContentfulFluid_withWebp
}
file {
url
}
}
JSX:
// GatsbyImage
<Img
fluid={image.fluid}
alt={image.title}
/>
// src
<div
style={{
backgroundImage: `url(${image.file.url})` // or image.fluid.src
}}
/>
After:
GraphQL:
image {
gatsbyImageData(
quality: 80
layout: FULL_WIDTH
)
}
JSX:
// GatsbyImage
<GatsbyImage
image={getImage(image)}
alt={image.title}
/>
// src
<div
style={{
backgroundImage: `url(${getSrc(image)})`
}}
/>
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-autonomy version below v1.2.7

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 v1.2.0)
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 v1.0.6)
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.

Gotchas

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.

Troubleshooting

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'

Error:
Missing onError handler for invocation 'building-schema', error was 'Error: Type with name "GatsbyImageLayout" does not exists'.
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.

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 [email protected] to update to the latest.

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 protected]. 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

Error:
error 'React' must be in scope when using JSX react/react-in-jsx-scope
Solution:
Make sure you use the JSX pragma for theme-ui at the top of your file:
/** @jsx jsx */

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.