Skip to main contentGatsby theme Carbon

V4.0 Migration

Carbon’s Gatsby Theme uses version 5 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 v4 of Carbon’s Gatsby Theme first if you haven’t already done so.

Breaking changes

  1. Bumped minimum version of Gatsby to 
    v5
  2. Gatsby files (i.e. gatsby-config.js and gatsby-node.js), need to be converted to .mjs (node modules) files.
  3. TBD…

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

  2. Update Gatsby plugins (including the theme)

    yarn upgrade-interactive --latest

  3. Run 

    yarn dev:clean
    to delete and rebuild your project’s development bundle

Troubleshooting

The following is still being updated.

Markdown link with title needs double quotes

this works

[I'm a markdown link with title](https://www.carbondesignsystem.com "Carbon's Homepage")

this does not

[I'm a markdown link with title](https://www.carbondesignsystem.com 'Carbon's
Homepage')
Edit this page on GitHub
Previous
Guides: v3.0 Migration
Next
Components: Accordion