> 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/developer-tools/gatsby/guides/v3-x-to-v4-x-migration-guide.md).

# v3.x to v4.x Migration Guide

### Overview

Chord’s [Gatsby starter](https://github.com/chordcommerce/gatsby-starter-autonomy) relies on a companion [Gatsby theme](https://github.com/chordcommerce/chord-ui/pkgs/npm/gatsby-theme-autonomy) to power its interactions with the Chord ecosystem. With the release of the new of Chord’s new React-based SDK, `react-autonomy`, the theme will now be powered by this lower-level package.

As such, the refactored integration of the theme in the starter will contain breaking changes.

**Why update?**

Going forward, all new SDK features and fixes will be made to `react-autonomy` (and consumed in `gatsby-theme-autonomy`). The new implementation of our SDK also comes with some great new features!

### Major Changes

**Typescript support**

`react-autonomy` and `gatsby-theme-autonomy` have Typescript support with type definitions.

**Removed ability to import services, selectors and actions via**

We have removed the ability to consume some internal parts of the Redux store in favour of better and more complete hooks.

**JSdoc documentation**

`react-autonomy` includes function documentation following the [JSDoc](https://jsdoc.app/) specification.

**Improved hooks and methods**

Names, parameters, and behavior has been standardized across the SDK.

**Environment variables**

We have added and renamed some environment variables and their corresponding plugin options needed to correctly configure the theme in your starter. See the list below.

**Removal of Sentry**

We have removed Sentry support from our SDKs.

### Migration Steps

### Change your environment variables and/or update the theme configuration in your starter

In the newest version of the starter, we have renamed some and added new environment variables:

{% code title=".env" %}

```shell
// before
GATSBY_ACS_API_URL=
GATSBY_ACS_STORE_NAME=
GATSBY_ACS_BRAND_NAME=

// after
GATSBY_CHORD_OMS_BRAND_NAME= // replaces GATSBY_ACS_BRAND_NAME
GATSBY_CHORD_OMS_STORE_ID= // ID of the store, provided by Chord
GATSBY_CHORD_OMS_STORE_NAME= // replaces GATSBY_ACS_STORE_NAME
GATSBY_CHORD_OMS_ID= // UUID of the OMS instance, provided by Chord
GATSBY_CHORD_OMS_TENANT_ID= // UUID of the tenant in the OMS, provided by Chord
GATSBY_CHORD_OMS_API_URL= // replaces GATSBY_ACS_API_URL
```

{% endcode %}

While mirroring these changes is not mandatory, you will need to update the configuration passed from your starter to the `gatsby-theme-autonomy` in `gatsby-plugin.js`:

```javascript
{
	resolve: '@chordcommerce/gatsby-theme-autonomy',
	options: {
    // new configuration
	  omsConfig: {
	    brandName: process.env.GATSBY_CHORD_OMS_BRAND_NAME,
	    storeId: process.env.GATSBY_CHORD_OMS_STORE_ID,
	    omsId: process.env.GATSBY_CHORD_OMS_ID,
	    tenantId: process.env.GATSBY_CHORD_OMS_TENANT_ID,
	    domain: process.env.GATSBY_CHORD_OMS_API_URL,
	  },
  },
}
```

### Update dependencies

Update your theme package:

{% code title="yarn" %}

```shell
yarn upgrade @chordcommerce/gatsby-theme-autonomy@^4.0.0
```

{% endcode %}

### Update React components

Hooks and method names have changed, so this will need to be updated throughout your code. Reference the documentation to see how they’ve changed. For example:

```javascript
- onClick={() => trackClickProduct(slug)}
+ onClick={() => trackProductClicked({ product: serializedProduct })}
```

### Remove dependencies on deprecated exports and deep imports

We have simplified the list of methods and hooks exported from `gatsby-theme-autonomy`. This means that you will no longer have access to previously exported members, like services, selectors, etc.

For example:

```javascript
- import { selectors } from '@chordcommerce/gatsby-theme-autonomy'
- import { usePreloadedState } from '@chordcommerce/gatsby-theme-autonomy'
- import { logSentryError } from '@chordcommerce/gatsby-theme-autonomy'
- import { trackProductViewed } from '@chordcommerce/gatsby-theme-autonomy/src/redux/actions/analytics'
```

### Add product serializer

As mentioned above, some methods now have a `product` argument you can include to add details about the product to the Segment tracking event. `gatsby-starter-autonomy/src/utils/chord/serialize.js` provides a couple of convenience methods that serialize the [Chord CMS default content model](https://docs.chord.co/autonomy-sdk/autonomy) into the correct object shape. You can customize these functions as needed, or write your own.


---

# 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/developer-tools/gatsby/guides/v3-x-to-v4-x-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.