V4.0 Migration
Version 4 of the Carbon Gatsby Theme uses version 5 of the Gatsby library. Please read through the release notes in the Gatsby documentation for more details.
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 v3 of the Carbon Gatsby Theme first if you haven’t already done so.
Breaking changes
-
You will need to convert your
andgatsby-config.jsto .mjs (node modules) files.gatsby-node.js -
HTML-style comments will no longer work inside of mdx files, you will need to use JavaScript-style comments with curly braces:
// Before<!-- Place comments here -->// After{/* Place comments here */}
- Homepage and default layouts have been moved from templates to layout components. Update any shadowing or links to template layouts.
// Beforeimport Layout from 'gatsby-theme-carbon/src/templates/Default';// Afterimport Layout from 'gatsby-theme-carbon/src/components/Layouts/Default';
- If you are shadowing the homepage you need to update the file path
packages/example/src/components/Homepage.js
// Beforeimport HomepageTemplate from 'gatsby-theme-carbon/src/templates/Homepage';// Afterimport HomepageTemplate from 'gatsby-theme-carbon/src/components/Layouts/Homepage';
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 v5 migration guide. To facilitate an easy upgrade path, we recommend upgrading to v3 of Carbon’s Gatsby Theme first if you haven’t already done so.
- Update Gatsby to v5
yarn add gatsby@latest-v5
- Update Gatsby plugins (including the theme)
yarn upgrade-interactive --latest
- Update graphql queries using the codemod:
npx gatsby-codemods@latest sort-and-aggr-graphql
- Update any files related to breaking changes listed above.
- Run to delete and rebuild your project’s development bundleyarn dev:clean
Troubleshooting
- // Before[Link](https://www.carbondesignsystem.com "Carbon")// After[Link](https://www.carbondesignsystem.com 'Carbon')