Updating Yarn Workspace Packages

Gatsby Themes are a reasonably simple, yet powerful concept that may be misunderstood due to the semantics of the word “theme” in other systems, such as WordPress. (I’m not criticising the naming convention as it works for me.) Nonetheless, Theming in Gatsby is a neat way of bundling/composing Gatsby-Plugins together, allowing for a modular approach that’s perhaps easier to manage. Themes are essentially a single plugin composed of many plugins.

Getting Started With Gatsby Themes

To implement themes, Gatsby utilises Yarn Workspaces, which are a little like projects within projects.

https://classic.yarnpkg.com/en/docs/workspaces/

https://www.gatsbyjs.com/blog/2019-05-22-setting-up-yarn-workspaces-for-theme-development/

One workspace “instance” behaves as the consuming site, and has the theme as a dependency. The gatsby-config.js file of this consumer is where all the specific site info is configured. This is the end user of our theme.

The second instance is the theme itself, and this is where all of the theme dependencies go. This allows logic to be ‘decoupled’ into more manageable pieces. There are also ways for allowing theme “shadowing”. If the user mirrors the folder structure of the theme, then they could overrule things in the theme. (Perhaps a little like a child-theme in WordPress.)

I think it’s fair to say that this is all sounds pretty complicated and unfortunately, I didn’t intend to write an article on the specifics of Yarn Workspaces and Gatsby Themes. Maybe sometime soon, in the meantime, I’ve linked to some free resources that I have found useful.

egghead.io/courses/gatsby-theme-authoring(opens in a new tab)

Youtube – Introducing Gatsby Themes Also worth checking out Chris’ personal Youtube channel for theming in more depth.

Updating Themes

So how do to deal with updates? The Gatsby ecosystem is very well maintained, and we all want to make the most of advances made in updates. It’s especially true with the new Gatsby-WordPress-Source-V4. As it relies on plugins installed at the WordPress source, which are being regularly updated (and provide a magical experience). There are times when updating the WordPress plugins requires updating the Gatsby-Source-WordPress-Plugin-V4 or vice versa.

Last year I had a few issues attempting to update and found this,

`yarn upgrade` refuses to work inside a workspace. #4442 https://github.com/yarnpkg/yarn/issues/4442

Fortunately Yarn has a neat command for checking all of your dependencies in accordance with semver in all of the Workspaces.

– Flags all the minor, hopefully, non-breaking updates.

yarn upgrade-interactive

-Flags all of the latest versions of the currently installed packages. Including potentially breaking updates.

yarn upgrade-interactive --latest

Each command will prompt the colour coded CLI to show you something, nice and handy. 

I like to make all my updates on a specific update branch and update packages in groups instead of upgrading them all together at the same time. If my site fails to build or Storybook fails to run, then I have some idea of what update may have caused the problem. All in all, it makes for a painless process to keep your custom Gatsby theme up to date.

That’s all for today, hoping to have more articles coming up soon!

PS – When updating to React17 I came across this error.

Error: ENOENT: no such file or directory, lstat '/Users/Gatsby-Sites/wpscr4-blog/packages/websume5/node_modules/semver'

I managed to get around this by manually updating the packages in the relevant package.json files, clearing all the node_modules and reinstalling everything via Yarn. I suspect this was caused by a clash between dependencies and peer dependencies.