When the Recipe project was created, we had to decide how we would package styles alongside React components for distribution within our applications. Ideally styles would be co-located and packaged with components, such that applications could use Recipe components without having to "remember" to manually include a separate stylesheet-per-component, or maintain a large global stylesheet.
The Recipe team made the choice to utilize the emotion css-in-js library, as it had already been well established as a tooling choice in ezcater's core web sites and web applications. Using emotion within Recipe solved the packaging and distribution problem, without requiring any additional configuration overhead for our existing applications.
In 2019, the Emotion maintainers shipped a major release of the emotion libraries (v10), adding some very useful new features and updating the internals for compatibility with React (by removing usage of deprecated APIs). Unfortunately for us as consumers of Emotion, this change required a significant update to Recipe that needed tight coordination with downstream applications.
Updating any major peer-dependency is somewhat challenging, and this situation was no different; applications could not upgrade Emotion without a corresponding Recipe release, but Recipe couldn't be upgraded without either cutting off support for applications that were not yet using the latest version of Emotion. 🐔 🥚
Once again, we find ourselves in a similar situation - the Emotion team have shipped a major release with breaking changes (v11), and progress in the react tooling ecosystem (supporting webpack 5) necessitates that we discontinue use of the prior version for compatibility.
This leaves us two options, upgrade emotion in Recipe (and all downstream applications), or remove Recipe's dependency on Emotion to unblock downstream applications from their own upgrades.
The Recipe team have chosen to do the latter. We've chosen a strategy that creates with some new opportunities:
The Recipe v12 release is the first step of this journey.
This release is a major version release and as such, will require migration steps for applications that currently use Recipe version 11.x or below.
While we have tried to minimize the number of major API changes, the following changes are considered breaking changes:
classNameprop in v11 will continue to accept a
classNameprop in v12, new specificity issues may occur if both the
classNameprovided is generated by emotion AND the associate styles override Recipe's component styles.
@recipe-ui/theme-marketplacepackage is not compatible with Recipe v12 (due to breaking change #2).
Other significant changes that are considered non-breaking include:
npm install @ezcater/recipe@latest---or---yarn upgrade @ezcater/recipe@latest
If you're building a marketplace application, you will also need install the latest marketplace theme as follows:
npm install @recipe-ui/theme-marketplace@latest---or---yarn add @recipe-ui/theme-marketplace@latest
Applications that need to support IE11 may require an updated list of polyfills to use Recipe.
The Recipe team recommend using Polyfill.io in your application. Polyfill.io will apply only the polyfills needed for the requesting browser.
We recommend using the following polyfill bundle features:
Recipe v11 internally used CSS Modules to define theme tokens, and required CSS importing support. This is no longer a requirement for Recipe v12.
If you needed to add bundler configuration to your app to transpile
node_modules in order to support Recipe 11, such as was the case for next.js applications, this additional configuration is no longer needed and can be removed from apps using Recipe v12.
For example, if your application previously needed to use the next-recipe-css plugin, this plugin is no longer needed in Recipe v12.
In prior versions of Recipe, in order for applications to render Recipe components on the server, additional set up was required to ensure styles would be included in the initial render. This set-up typically included the use of Emotion's
This setup is no longer required to support the server rendering of Recipe components, and may safely be removed from your application (if your application is not relying on emotion directly).