Skip to main contentGatsby theme Carbon

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

  1. You will need to convert your 

    gatsby-config.js
    and 
    gatsby-node.js
    to .mjs (node modules) files.

  2. 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 */}
  1. Homepage and default layouts have been moved from templates to layout components. Update any shadowing or links to template layouts.
// Before
import Layout from 'gatsby-theme-carbon/src/templates/Default';
// After
import Layout from 'gatsby-theme-carbon/src/components/Layouts/Default';
  1. If you are shadowing the homepage you need to update the file path 
    packages/example/src/components/Homepage.js
// Before
import HomepageTemplate from 'gatsby-theme-carbon/src/templates/Homepage';
// After
import 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.

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.

  1. Update Gatsby to v5
yarn add gatsby@latest-v5
  1. Update Gatsby plugins (including the theme)
yarn upgrade-interactive --latest
  1. Update graphql queries using the codemod:
npx gatsby-codemods@latest sort-and-aggr-graphql
  1. Update any files related to breaking changes listed above.
  2. Run 
    yarn dev:clean
    to delete and rebuild your project’s development bundle

Troubleshooting

  • // Before
    [Link](https://www.carbondesignsystem.com "Carbon")
    // After
    [Link](https://www.carbondesignsystem.com 'Carbon')
  • PATH_PREFIX = /website/prefix
Edit this page on GitHub
Previous
Guides: v3.0 Migration
Next
Components: Accordion