info icon

Carbon’s Gatsby Theme uses version 4 of the Gatsby library. This update combines the control and scalability of server-side rendering with the performance of static-site generation. The major version change comes with the potential for breaking changes, this guide aims to cover the most likely issues a site built with the Carbon Gatsby theme might encounter. To have the smoothest possible experience, we recommend upgrading to v2 of Carbon’s Gatsby Theme first if you haven’t already done so.

Breaking changes

Bumped minimum version of Gatsby to
```
v4
```
Removed
```
carbon-components-react
```
and
```
carbon-components
```
in favor of installing
```
@carbon/react
```
effectively migrating to Carbon v11.

Gatsby migration guide

In this section we’ll cover the most likely issues site’s built with the Carbon gatsby theme might encounter when migrating. If you encounter any issues, or your site leverages more advanced gatsby configuration, check to see if it’s covered in the official Gatsby v4 migration guide. To facilitate an easy upgrade path, we recommend upgrading to v2 of Carbon’s Gatsby Theme first if you haven’t already done so.

Note: We’ll use yarn for the shell commands here. Replace them with the

npm

equivalent if your project uses

npm

as its package manager.

Update Gatsby to v4

yarn add gatsby@latest-v4
Copy to clipboard

Update gatsby plugins (including the theme)

yarn upgrade-interactive --latest
Copy to clipboard

Run
```
yarn dev:clean
```
to delete and rebuild your projects development bundle

Troubleshooting

Try deleting your node_modules, running
```
yarn cache clean
```
and
```
yarn install
```
(or
```
npm cache clean --force
```
and npm install)
Feel free to reach out in the #gatsby-theme-carbon slack channel or open an issue on GitHub

Carbon v11 migration guide

As part of this release, the theme has been updated to use Carbon v11. In this section we’ll cover the areas that will need to be updated in relation to this dependency upgrade.

Update your color, motion, and type tokens where appropriate. Use the migration guide from Github for a fantastic token reference guide.

Pro tip: When attempting to build your local dev environment, it will usually throw an error because of an old v10 token. Do a search for the v10 token in question throughout the entire project. Once found, copy it to your clipboard, then switch over to the migration guide on Github. Hit

CMD+F

to search the page to find/replace with the corresponding v11 token.

Update icon usage

As part of v11, the usage pattern for icons has changed. Icons are no longer imported by size, instead size is configured via the

size

prop. Full details can be found in the Carbon v11 migration guide.

import { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';

function MyComponent() {
  return (
    <>
      <Add32 />
      <Add24 />
      <Add20 />
      <Add16 />
    </>
  );
}
Copy to clipboard

import { Add } from '@carbon/icons-react';

function MyComponent() {
  return (
    <>
      <Add size={32} />
      <Add size={24} />
      <Add size={20} />
      <Add />
    </>
  );
}
Copy to clipboard

A very easy way to make this change is to use the automated migration tool available from the Carbon Upgrade CLI. You can run a test of this automated migration against your codebase with the following command. When ready to write the changes, additionally pass the

-w

flag

npx @carbon/upgrade migrate icons-react-size-prop
Copy to clipboard

This automated migration will not rewrite imports in

.mdx

files. Search all your

.mdx

files for

@carbon/icons-react

and manually update their import. Additionally update their usage to include the appropriate

size

prop.

Remove any prefix imports. Replace the following in your classnames:

<div className={`${prefix}--fancy-class`}>
Copy to clipboard

<div className='cds--fancy-class'>
Copy to clipboard

The tips above should get you most, if not all of the way there, but your mileage may vary based on how much you have customized your site. If you have still have issues check out the v11 migration guides below.

v11 Migration Guide on Github

v11 Migration Guide

Edit this page on GitHub

Guides: v2.0 Migration