V2.0 Migration
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 theme provider and its dependenices.emotion
- This impacts sites styling their project using and depending on theme values supplied by the themeemotion
- If this applies to your project, you can recreate the theme’s emotion
integration installing and replicating theemotioncomponent andThemeProvider. Finally, you’ll want to shadowtheme.jsto add back thewrap-root-element.jswrapper.ThemeProvider
- This impacts sites styling their project using
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.
-
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
orsizeswithresolutions. Do a project wide search forgatsby-image. Check to make sure that you’re not using these deprecated propsgatsby-image -
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} />;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 andFooter.Header
- Change the file name to inside each corresponding folder. More info can be found in the shadowing docsindex.js
- Create a folder each for
-
If you have a custom webpack config, be sure your config is compatible with Webpack 5 (the version Gatsby 3 uses)
-
Run
to delete your projects development bundlenpx gatsby clean -
Run
yarn dev
Troubleshooting
- Try deleting your node_modules, running andyarn cache clean(oryarn installand npm install)npm cache clean --force
- Feel free to reach out in the #gatsby-theme-carbon slack channel or open an issue on GitHub