Skip to content

Migrating

This reviews any breaking changes. You can check the changelog file on GitHub for more detailed list of non-breaking changes.

v6.0.0

This is a doozy of an update but stay with me and you will get there in the end. Hopefully with minimal pain. If you run into any problems please submit an issue and I will do my best to help. You can view an umbrella issue of the move to v6.0 as well.

Unified versioning

The themes and starters are now using unified versioning and are all at v6.0.0 (or above). For some of the packages this is a jump straight from v1.0 to v6.0, the reason for this is that I had one package which was already at v5.x so I had to move everything to v6.x.

Part 1: Gatsby and Theme-UI

  1. Update all of your Gatsby related packages to their latest versions. Gatsby should be v3.x and above. All Gatsby-Theme-Catalyst packages should be v6.x and above.

  2. Run gatsby clean in your project root, this is going to help prevent any issues down the line for us with images.

  3. Upgrade to gatsby-plugin-image, you should be able to follow their migration guide and use the codemod to complete this pretty painlessly. You may need to go back and tweak/adjust after running the codemod but it should get you most of the way there.

  4. Find and replace Styled with Themed, double check where this happens in your code base but you should be pretty safe to do this. You can read more about migration to Theme-UI v0.6.x.

  5. Find and replace SEO with Seo, double check where this happens in your code base but you should be pretty safe to do this. This has been updated so that you do not get console warnings about using pascal case in components.

  6. Run gatsby develop and check to see if it builds successfully. You are going to notice a few more things that need to be changed but you should get a successful development build at this point.

Part 2: Branding component

Customizing logo and branding was more of a headache than it needed to be in past versions with too many fancy API options like displaySiteTitleMobile to try and give you more flexibility. It wasn’t worth it. I refactored this to use component shadowing to put full power back in the hands of the developer for site branding.

  1. Copy and paste the src/components/header/branding.js file from one of the starters into your site.
  2. Copy and paste the src/gatsby-theme-catalyst-header-top/branding.js file from one of the starters into your site. You may need to modify this name to match the shadowed header theme, e.g. header-bigtop instead of header-top if that is the header theme you are using.

A few notes on the changes:

  • Logo sizing is now coded directly into this branding component and now longer sourced from Theme-UI, again this gives you more options for customization and direct presentational control.
  • Removed API options invertLogo, displaySiteTitle, displaySiteTitleMobile, displaySiteLogo, displaySiteLogoMobile. You can now do this all yourself in the shadowed component using plain CSS.
  • Take a look at gatsby-starter-catalyst to see how this is done. Also note the shadowing of the branding component as well.

Part 3: API Reorganization

In most cases, if you were using default options, this will all “just work”. You will only need to check this if you were specifying some custom options. The main change is that I moved API options to their respective themes, e.g. footerContentLocation is now an option for the footer theme and not the core theme. This will give me more flexibility in the future and is more intuitive. The updated theme options are documented in the Readme.md files of the respective themes.

  • useSocialLinks renamed to useHeaderSocialLinks and useFooterSocialLinks
  • useColorMode, useHeaderSocialLinks, and useStickyHeader are now options for respective header themes. Note that gatsby-theme-catalyst-header-bigtop does not have a sticky option.
  • footerContentLocation and useFooterSocialLinks are now options for the footer theme
  • Removed options invertLogo, displaySiteTitle, displaySiteTitleMobile, displaySiteLogo, displaySiteLogoMobile. You can now do this all yourself completely custom in the shadowed components. See above for details.

Other breaking changes

These should not affect most users, but could if you were doing some advanced stuff.

  • Removal of react-scroll and reorganization/simplification of the nav components as a result. If you were using anchor links make sure they are linking as /#anchor-link including the slash so it works properly with Gatsby Link component. You can also remove the type field from your links in gatsby-config. For most users this won’t be a breaking change, but if you were doing some advanced component shadowing based on existing theme files in the nav you would need to change a file name.
  • Removal of remark-katex due to the difficulties maintaining this package and the bugs it currently has working with MDX content. You should implement this directly yourself, or if needed submit an issue and we can have a discussion about it.
  • Removal of HomeContext, not needed now that react-scroll is gone. If you were using this you can re-implement this yourself using the code that was there previously.
  • Move from normalize.css to modern-normalize.css
  • Removed SanityThemeProvider which was experimental and never got working the way I wanted it to. This might come back again in the future but has always been marked experimental.

Other notable changes

  • Added rssDescription theme option that was missing to the blog theme
  • Added useAlertBanner theme option for the core theme which inserts a banner overtop of your site that can be customized with component shadowing.
  • Improved a11y for the header themes
  • Added framer-motion as a dependency to the core theme as I am using it in multiple places now and will likely use it more in the future for other animations

catalyst-header-side v2.0.0

  • Breaking Change: This is a visually breaking change. Added support for dropdowns that function as toggles, instead of the pure CSS on hover behaviour that was there before. I also adjusted the default text alignment to be left as this is more expected. You can nudge it back to the centre using variants.
variants: {
navUl: {
width: "100%",
alignItems: ["center", null, "center", null, null],
},
},

catalyst-core v3.0.0 and other packages with a major bump

  • BREAKING CHANGE: Removed gatsby-plugin-offline from the core theme as there are more considerations and impacts from service workers than should be included in the core theme. This plugin has a lot of power and I would suggest using it on most Gatsby sites but want to leave this as an optional addition versus a forced inclusion in the core theme. If you want to include gatsby-plugin-offline in your site you would just add it to your main gatsby-config.js file following the instructions at the link above.

catalyst-sanity v4.0.0, catalyst-bery v2.0.0, catalyst-hydrogen v.4.0.0

  • BREAKING CHANGE: In order to support split links properly in the header components I needed to update the schema coming from your SANITY studio. Unfortunately this means you also need to update your schema and re-deploy the graphQL schema.

  • Copy and paste sanity-studio/schema/menuLinks.js from any current SANITY based starter into your existing studio. Update the location field in your studio for the menu links. The default behaviour is to have the links on the right but now it supports handling them on the left as well.

  • Redeploy the graphql schema with the command sanity graphql deploy

catalyst-sanity v3.0.0 and catalyst-hydrogen v3.0.0

  • There was a breaking change in order to enable to support for categories in SANITY based blogs. This required adding a schema for blog categories which needs to be included in older installations of these themes, even if you are not using a blog.
    • Copy gatsby-starter-catalyst-sanity/sanity-studio/schemas/category.js and put it in your own schemas folder in your installation.
    • Import the category.js schema in sanity-studio/schemas/schema.js and make sure it is included in the concatenated set of export schemas
    • Run sanity graphql deploy to redeploy your GraphQL schema

catalyst-core v2.0.0 and other v2.0.0 themes

  • This was a visually breaking change to make it easier to remove dark mode from your site. gatsby-theme-catalyst-core exports a “base theme” which is used in the starters to merge with any theme customizations. By default it was including a dark mode meaning that it was difficult to remove dark mode without overriding all of the key value pairs in your site. If you were relying on the core theme for your site colors then you will now need to explicitly define those in src/gatsby-plugin-theme-ui/index.js.

  • This required a version bump for most other themes as they rely on the core theme. No other breaking changes were introduced.

  • This will particularly affect gatsby-theme-catalyst-helium as your dark mode was being merged in. Ensure that your dark mode colors object located at src/gatsby-plugin-theme-ui/index.js looks similar to this:

dark: {
background: baseColors.gray[9],
text: baseColors.gray[1],
textGray: "#9f9f9f",
primary: "#e6da00",
secondary: "#9933CC",
muted: "#1a2431",
accent: "#363636",
link: "#e6da00",
header: {
background: "transparent",
text: baseColors.gray[1],
textOpen: baseColors.gray[1],
backgroundOpen: baseColors.gray[8],
icons: baseColors.gray[1],
iconsOpen: baseColors.gray[1],
},
footer: {
background: "transparent",
text: baseColors.gray[1],
links: baseColors.gray[1],
icons: baseColors.gray[1],
},
},
  • Here is another example from gatsby-starter-catalyst and you can see the full colors are now defined in the starter whereas before they were being merged from the baseTheme.
import { merge } from "theme-ui"
import { BaseTheme } from "gatsby-theme-catalyst-core"
import { tailwind, baseColors } from "@theme-ui/preset-tailwind"
export default merge(BaseTheme, {
// Modifications to the base theme go here. This is an example changing colors and using variants to change your navigation links. Uncomment the code below to see what happens.
colors: {
...tailwind.colors,
background: baseColors.gray[1], //Try "#954264",
text: baseColors.gray[8],
textGray: "#6e6e6e",
primary: baseColors.blue[7],
secondary: baseColors.orange[7],
accent: baseColors.orange[2],
highlight: baseColors.orange[5],
muted: baseColors.gray[2],
header: {
background: baseColors.gray[2],
backgroundOpen: baseColors.blue[2],
text: baseColors.gray[8],
textOpen: baseColors.gray[8],
icons: baseColors.gray[6],
iconsOpen: baseColors.gray[8],
},
footer: {
background: baseColors.gray[2],
text: baseColors.gray[8],
links: baseColors.gray[8],
icons: baseColors.gray[8],
},
// You can delete dark mode by removing the "modes" object and setting useColorMode to false in gatsby-theme-catalyst-core
modes: {
dark: {
background: baseColors.gray[9],
text: baseColors.gray[1],
textGray: "#9f9f9f",
primary: "#458ad2",
secondary: baseColors.orange[7],
accent: baseColors.gray[8],
highlight: baseColors.orange[5],
muted: baseColors.gray[8],
header: {
text: baseColors.gray[1],
textOpen: baseColors.gray[1],
background: "#232946",
backgroundOpen: baseColors.gray[8],
icons: baseColors.gray[1],
iconsOpen: baseColors.gray[1],
},
footer: {
background: "#232946",
text: baseColors.gray[1],
links: baseColors.gray[1],
icons: baseColors.gray[1],
},
},
},
},
variants: {
siteTitle: {
fontSize: [3, 4, null, 5, null],
},
},
})

catalyst-sanity v2.0.0

  • The default queries and templates were updated to rely on excerpt instead of _rawExcerpt. Going forward though this allows for an easier authoring experience and simpler sanity studio as the post and project excerpts are automatically generated based on the post content. If you are migrating from an older version of gatsby-theme-catalyst-sanity it should work without any changes however your “excerpts” are now sourced directly from the post content rather than being sourced from the excerpt field in sanity studio.

You can see examples of the changes in the src/components/queries folder and src/components/templates folder.

catalyst-blog v2.0.0

  • This was a breaking change to allow for better component architecture, remove the need for a featuredImage and add in a number of additional frontmatter fields, like socialImage.
  • Rewrite of the core blog theme to be more basic and act as as “data” theme with fewer presentational components. Less you have to undo as a developer, however if you were using version 1.0 or earlier a lot of the styles you would have had are gone. The good news however is that these styles can be easily added back in via component shadowing. You can look at gatsby-theme-catalyst-lithium to see how this is done and copy those files and tweak to your liking.
  • If you have trouble migrating let me know and I will help out. v1.0 of this theme will work for a long time to come, so no rush.
  • You can see an example of this migration on my personal blog, https://github.com/ehowey/erichoweydev, if you look at the code you can see how the components are shadowed and the blog is implemented.

v1.0.0

  • Move your theme-ui file from src/gatsby-theme-catalyst-core/theme.js -> src/gatsby-plugin-theme-ui/index.js. No other change should be needed. This was done to be more in line with recommended best practice. There is now a ‘base theme’ for Theme-UI which is exported from gatsby-theme-catalyst-core. You can use this to write smaller and more condensed themes in the starters using the following syntax:
import { merge } from "theme-ui"
import { BaseTheme } from "gatsby-theme-catalyst-core"
export default merge(BaseTheme, {
// Modifications to the base theme go here. This is an example changing colors and using variants to change your navigation links. Uncomment the code below to see what happens.
})
  • Depreciated gatsby-theme-catalyst-writer in favor of gatsby-theme-catalyst-hydrogen. If you were using the writer theme it will continue to work, and will work for a long time to come. If you want to migrate to hydrogen then it will be possible with a little effort as the expected data structures from SANITY were unchanged. The main change you need to make is to ensure you have the same SANITY.io schema files in your site as in the theme as this is where the GraphQL query is generated from. If you are having trouble migrating please get in touch via issues and I will help you out.

  • This is technically not a breaking change but it could change your sites appearance. Base navigation link styles were simplified in the structural themes and then added back in for the presentational themes using variants in the Theme-UI file. You can see an example of this in gatsby-theme-catalyst-hydrogen if you would like to see how to do it on your site, look in gatsby-theme-catalyst-hydrogen/src/gatsby-plugin-theme-ui/index.js towards the end of the file.

Removal of isMobile Context and mobileMenuBreakpoint

These are depreciated and will stop working post v1.0. There was a perfomance issue with SSR and javascript that was causing a flash of unstyled content. I have reverted back to using normal media queries for changing to the mobile menu at the second breakpoint, 768px by default.

© 2021 Gatsby Theme Catalyst