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.

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.

© 2020 Gatsby Theme Catalyst