info icon

This update introduces several big improvements to Gatsby sites including incremental builds, fast refresh, and image processing. 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.

Breaking changes

Bumped minimum version of Gatsby to
```
v3
```
Removed the
```
emotion
```
theme provider and its dependenices.
- This impacts sites styling their project using
```
emotion
```
  and depending on theme values supplied by the theme
- If this applies to your project, you can recreate the theme’s emotion integration installing
```
emotion
```
  and replicating the
  ThemeProvider
  component and
  theme.js
  . Finally, you’ll want to shadow
  wrap-root-element.js
  to add back the
```
ThemeProvider
```
  wrapper.

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 v3 migration guide.

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 v3

yarn add gatsby@latest-v3
Copy to clipboard

Update gatsby plugins (including the theme)

yarn upgrade-interactive --latest
Copy to clipboard

Check to see if you’re using
```
sizes
```
or
```
resolutions
```
with
```
gatsby-image
```
. Do a project wide search for
```
gatsby-image
```
. Check to make sure that you’re not using these deprecated props

Check your Sass (and potentially JSON) to ensure they’re imported as ES Modules. “Default exports” are no longer supported.

import styles from './MySpan.module.scss';
import metadata from './metadata.json';
const MySpan = () => <span className={styles.mySpan} />;
Copy to clipboard

import { mySpan } from './MySpan.module.scss';
// Or import * as styles from './MySpan.module.scss'
import * as metadata from './metadata.json';
const MySpan = () => <span className={mySpan} />;
Copy to clipboard

Make sure to update the path of your shadowed components (Footer and Header).
- Create a folder each for
```
Footer
```
  and
```
Header
```
  .
- Change the file name to
```
index.js
```
  inside each corresponding folder. More info can be found in the shadowing docs
If you have a custom webpack config, be sure your config is compatible with Webpack 5 (the version Gatsby 3 uses)
Run
```
npx gatsby clean
```
to delete your projects development bundle
Run
```
yarn dev
```

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

Edit this page on GitHub

Guides: Styling

Guides: v3.0 Migration

V2.0 Migration

Breaking changes

Migration guide

Troubleshooting