V3.0 Migration
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 andcarbon-components-reactin favor of installingcarbon-componentseffectively migrating to Carbon v11.@carbon/react
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.
-
Update Gatsby to v4
yarn add gatsby@latest-v4 -
Update gatsby plugins (including the theme)
yarn upgrade-interactive --latest -
Run
to delete and rebuild your projects development bundleyarn dev:clean
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
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.
- 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
import { Add32, Add24, Add20, Add16 } from '@carbon/icons-react';function MyComponent() {return (<><Add32 /><Add24 /><Add20 /><Add16 />
import { Add } from '@carbon/icons-react';function MyComponent() {return (<><Add size={32} /><Add size={24} /><Add size={20} /><Add />
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
npx @carbon/upgrade migrate icons-react-size-prop
- Remove any prefix imports. Replace the following in your classnames:
<div className={`${prefix}--fancy-class`}>
<div className='cds--fancy-class'>
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.