v1.2.7 to v2.0.0 Migration Guide

22min
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
﻿Gatsby – Migrating from v2 to v3﻿
﻿Gatsby – Migrating from v3 to v4﻿
﻿Gatsby – Migrating from gatsby-image to gatsby-plugin-image﻿
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.
Upgrade Guide
1. Update Dependencies
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
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.
JS
module.exports = {
  plugins: [
    // ...
    'gatsby-plugin-image',
    'gatsby-plugin-sharp',
    'gatsby-transformer-sharp',
    // ...
  ],
}
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  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:
GraphQL
fluid(maxWidth: 500, quality: 80) {
  ...GatsbyContentfulFluid_withWebp
}
fluid(maxWidth: 500, quality: 80) {
  ...GatsbyContentfulFluid_withWebp
}
﻿
After:
GraphQL
gatsbyImageData(
  quality: 80
  layout: CONSTRAINED
  width: 500
)
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:
GraphQL
image {
  title
  fluid(maxWidth: 500, quality: 80) {
    ...GatsbyContentfulFluid_withWebp
  }
  file {
    url
  }
}
image {
  title
  fluid(maxWidth: 500, quality: 80) {
    ...GatsbyContentfulFluid_withWebp
  }
  file {
    url
  }
}
﻿
JSX:
JS
// GatsbyImage
<Img
  fluid={image.fluid}
  alt={image.title}
/>
// src
<div
  style={{
    backgroundImage: `url(${image.file.url})` // or image.fluid.src
  }}
/>
// GatsbyImage
<Img
  fluid={image.fluid}
  alt={image.title}
/>
// src
<div
  style={{
    backgroundImage: `url(${image.file.url})` // or image.fluid.src
  }}
/>
﻿
After:
GraphQL:
GraphQL
image {
  gatsbyImageData(
    quality: 80
    layout: FULL_WIDTH
  )
}
image {
  gatsbyImageData(
    quality: 80
    layout: FULL_WIDTH
  )
}
﻿
JSX:
JS
// GatsbyImage
<GatsbyImage
  image={getImage(image)}
  alt={image.title}
/>

// src
<div
  style={{
    backgroundImage: `url(${getSrc(image)})`
  }}
/>
// 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 )
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.
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:
Text
Missing onError handler for invocation 'building-schema', error was 'Error: Type with name "GatsbyImageLayout" does not exists'.
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 gatsby-plugin-gatsby-cloud@latest 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 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.
theme-ui JSX pragma
Error:
Text
error  'React' must be in scope when using JSX  react/react-in-jsx-scope
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:
JS
/** @jsx jsx */
/** @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.
Updated 03 Mar 2023
Did this page help you?
Guides
v3.x to v4.x Migration Guide