V2.0 Migration

Earlier this year, Gatsby released v3 of their library. 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

Update gatsby plugins (including the theme)

yarn upgrade-interactive --latest

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.

Before
import styles from './MySpan.module.scss';
import metadata from './metadata.json';

const MySpan = () => <span className={styles.mySpan} />;

After
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} />;

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

Components: Accordion