---
title: v1.2.7 to v2.0.0 Migration Guide
slug: oms/v127-to-v200-migration-guide
docTags: 
createdAt: 2022-11-07T21:32:52.000Z
---

## 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](https://www.gatsbyjs.com/gatsby-4/)**!**

### Major Changes:

### Gatsby 4

`v2.0.0` requires [Gatsby 4](https://www.gatsbyjs.com/gatsby-4/). Gatsby 4 has a variety of performance improvements. You can read more about [Gatsby 4 here](https://www.gatsbyjs.com/gatsby-4/).

### 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](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/).

## Reading

- [Gatsby – Migrating from v2 to v3](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/)
- [Gatsby – Migrating from v3 to v4](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/)
- [Gatsby – Migrating from gatsby-image to gatsby-plugin-image](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide)

:::hint{type="info"}
**Note**: The scope of this guide covers updating the`gatsby-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

1. Update `@chordcommerce/gatsby-theme-autonomy` to `^2.0.0`
2. Update `@chordcommerce/chord-magic` to `^1.1.0`
3. Update `gatsby` to `^4.4.0`
4. Update `theme-ui` and `gatsby-plugin-theme-ui` to `^0.12.1`
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](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/#update-gatsby-related-packages) for more information on updating Gatsby plugins.

:::hint{type="warning"}
**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](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v3-to-v4/#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](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide) 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](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide/#how-to-migrate) for more information.

```javascript
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](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide/#how-to-migrate) for more information.

:::hint{type="danger"}
**Note**: the `gatsby-plugin-image` codemod removes the theme-ui [JSX pragma](https://www.gatsbyjs.com/blog/2019-08-02-what-is-jsx-pragma/) (`/** @jsx jsx */` at the top of the file), see [theme-ui JSX pragma](v1.2.7-to-v2.0.0-migration-guide.md#error-react-must-be-in-scope) and ensure the JSX pragma is included in all theme-ui components.
:::

:::hint{type="info"}
**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](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide).

**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
}
```

After:

```graphql
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](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/#getimage) and [getSrc](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/#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
  }
}
```

JSX:

```javascript
// 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
  )
}
```

JSX:

```javascript
// GatsbyImage
<GatsbyImage
  image={getImage(image)}
  alt={image.title}
/>

// src
<div
  style={{
    backgroundImage: `url(${getSrc(image)})`
  }}
/>
```

See [Migrating from gatsby-image to gatsby-plugin-image](https://www.gatsbyjs.com/docs/reference/release-notes/image-migration-guide/#how-to-migrate) or the [Gatsby Image Plugin Reference Guide](https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/) 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&#x20;

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](https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/#graphql-__typename-field-is-no-longer-added-automatically) 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'.
```

**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](https://react-hook-form.com/migrate-v5-to-v6/) and [react-hook-form v6 to v7 Migration Guide](https://react-hook-form.com/migrate-v6-to-v7/).

### theme-ui JSX pragma

**Error**:

```Text
error  'React' must be in scope when using JSX  react/react-in-jsx-scope
```

**Solution**:

Make sure you use the [JSX pragm](https://www.gatsbyjs.com/blog/2019-08-02-what-is-jsx-pragma/)a for `theme-ui` at the top of your file:

```javascript
/** @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](https://www.gatsbyjs.com/docs/reference/functions/getting-started/). 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.