Recipe is the ezCater design system in production since 2018, which we've recently open sourced. Check out the documentation site for examples and a catalog of React components we use to build amazing experiences for our customers.

First things first. I’m not going to be talking about a 2002 science fiction movie about a future in which feelings and artistic expression are outlawed.

Instead, I’ll be talking about the emotion 👩‍🎤  CSS-in-JS library we’ve been using since early 2018 for authoring and distributing styles for our React applications, and more specifically, why the Recipe team decided to wave a fond farewell to the library, what we’re doing instead, and why we’re excited about it!

Prologue

^{(The context here is an extract from our v12 migration docs, so skip ahead to the next heading if you’d like)}

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:

• Solving the "Recipe theming" story for supporting multiple applications with different branding/marketing focuses

• Enabling a solid story for creating new "branded" components outside of Recipe by utilizing Recipe's theming engine

• Reducing runtime overhead by leveraging static CSS, instead of CSS generated at runtime

• Providing a path to optimizing performance by leveraging the extraction of CSS at build-time

• Creating a developer-friendly experience by leveraging TypeScript at the core our our styling engine.

I’ll be needing stitches

There we go again. Despite what Google search may lead you to believe, I’m not going to be talking about the 2015 Shawn Mendes top 10 hit.

No, in this case I’m referring to the stitches 🪡 🧵 CSS-in-JS library. I’m not actually going to do a deep dive on this library though, as the Recipe team are intentionally keeping this dependency internalized (more on this shortly).

Instead, let’s have a very quick look at some of stitches' killer features:

• First-class variant API. Seriously, this is a huge winner for the Recipe team. A before/after comparison of Recipe’s layout component shows how powerful this abstraction can be. In addition to reducing the layout component footprint from 254 loc to 123 loc, the declarative variant API is much easier to understand (both by devs and static extraction tooling).

• Fully-typed API. This is both great for the devs maintaining Recipe, who can now see a typed list of CSS-variable available to any given component, but also to application developers who are provided with rich type definitions for component responsive props.

• Custom utilities for authoring CSS with property shorthands (like tailwind pt, pr, pb, pl), property bundles (like tailwind px, py, inset etc), CSS polyfills and more.

• Best-in-class debugging experience. Stitches generates styles for component variants with BEM-like syntax, for example, if you take a peek at accented cards in Recipe’s doc-site, you’ll see class names suffixed --imagePosition-top and --accent-info.

We’ve paired stitches with our very own snitches library, allowing us to use stitches' fantastic core API, while eliminating the need for any additional setup to supporting server-side-rendering.

Shhhh, keep this to yourself!

As I mentioned, the Recipe team are intentionally keeping the stitches dependency internalized. You won’t see stitches in Recipe’s public API, nor should you have to give any consideration to stitches when installing Recipe or using Recipe components.

Internalizing this dependency is critical for us to avoid the peer-dependency challenges we had with emotion. It is also they key to the Recipe team’s plans for future performance optimizations; we want to eliminate the need for a JavaScript runtime for styling applications. While authoring styles in TypeScript gives us a fantastic developer experience, JavaScript is still the most expensive resource, and having all styles generated at build time (just like SASS, LESS etc) will allow us to minimize this cost without sacrificing the authoring experience.

Read More