> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/shopify/developer-tools/gatsby/guides/v1-5-0-to-v2-0-0-migration-guide.md).

# 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**](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 style="info" %}
**Note**: The scope of this guide covers updating the`gatsby-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.
{% endhint %}

## Upgrade Guide

### 1. Update dependencies

1. Update `@chordcommerce/gatsby-theme-performance` to `^2.0.0`
2. Update `gatsby` to `^4.4.0`
3. Update `theme-ui` and `gatsby-plugin-theme-ui` to `^0.12.1`
4. 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 style="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
{% endhint %}

### 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

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](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 style="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](#theme-ui-jsx-pragma) and ensure the JSX pragma is included in all theme-ui components.
{% endhint %}

{% hint style="info" %}
**Note**: the `gatsby-plugin-image` codemod may add some undesirable code style changes. Be sure to check the diff before committing.
{% endhint %}

### 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
image {
  title
  fluid(maxWidth: 500, quality: 80) {
    ...GatsbyContentfulFluid_withWebp
  }
  file {
    url
  }
}
```

{% code title="JSX" %}

```javascript
// GatsbyImage
<Img
  fluid={image.fluid}
  alt={image.title}
/>
// src
<div
  style={{
    backgroundImage: `url(${image.file.url})` // or image.fluid.src
  }}
/>
```

{% endcode %}

**After**:

```graphql
image {
  gatsbyImageData(
    quality: 80
    layout: FULL_WIDTH
  )
}
```

{% code title="JSX" %}

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

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

{% endcode %}

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

## 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](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:**

```
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.

### Cannot read properties of undefined (reading 'initialized')

**Error**:

```
Cannot read properties of undefined (reading 'initialized')

./node_modules/@segment/consent-manager/esm/consent-manager-builder/analytics.js:22
```

**Solution**:

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 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**:

```
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:

```
/** @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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/chord-oms/shopify/developer-tools/gatsby/guides/v1-5-0-to-v2-0-0-migration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.