Consuming stitches at the "libary" level

[dylanklohr]

Before any of the following, I want to say that stitches feels like a fantastic library and I've incredibly enjoyed utilizing it and seeing it grow over the past several months.

Context

Like many others, we're working to build a design system with reusable artifacts for quickly building quality views. Most of the artifacts we have today are implemented as react components, with styled-components being utilized for styling.

We've been looking to switch over to stitches for both the DX improvements and the ability for the component API to better mirror what say a Figma (or eventually, maybe Modulz 😄) option pane defines styles, as well as the performance improvements offered by avoiding prop interpolation at run-time.

To this point, we've implemented a few packages with a common package consuming @stitches/react underpinning them, but I recently ran into something that we first saw referenced on #357 that at the time, I believed to have a workaround for – I now believe that workaround to be insufficient 😔.

Problem

As stitches isn't incredibly widespread, yet, this may not be something that the "app-level" consumer has run across yet, but I have no doubt they will as stitches continues to grow in popularity.

From what I can tell, even with the addition of insertMethod in #456, it isn't possible to consume stitches in > 1 place reliably at the app-level without external encapsulation via the shadow DOM, due to the following:

1. Without providing a custom insertMethod, stitches looks to inject any generated CSS into a single <style id="stitches /> element.
2. With/without a custom insertMethod being provided, the classes, CSS custom properties, etc. that stitches creates have no manner of collision avoidance without strict external mechanisms such as shadow DOM encapsulation.

Example of Problem Actualized

Note: the example below is outlined with an architecture similar to the use-case I describe above in Context, but in my testing, this issue is present in any situation in which the above strict encapsulation methods aren't/cannot be practically used.

• 1 Package that defines a reusable stitches configuration: @scope/stitches-config-pkg
• 2 Packages consuming @scope/stitches-config-pkg: @scope/pkg-1, @scope/pkg-2
• 1 Application consuming @scope/pkg-1, @scope/pkg-2

In the above dependency graph, the unpinned @scope/stitches-config-pkg version (^1.0.0) in @scope/pkg-1 and @scope/pkg-2 might temporarily mask the issue described above, if the Consuming Application is able to utilize dependency deduping at the package level to effectively create a singleton instance of the @scope/stitches-config-pkg in its node_modules, but this is hardly fool proof or something that I imagine we should be relying on...

If at any point, >1 instance of createCss, or the utilities it returns, are present in the dependency graph above, we'll be left in a position in which >1 entities will be trying to generate their own CSS to insert into the <style id="stitches" /> element, wiping out any styles that were present in it before. One important thing to note here, is that without the ability to create this sort of "internal" collision avoidance, any package that looks to consume stitches that then outputs styles to <style id="stitches" /> (or some, generic element) would not be something that even a major version bump in said package could protect against, from what I can tell.

Given stitches' api, I don't believe the thought of creating a reusable single-source-of-truth stitches config is far-fetched. I actually believe it to be one of the greatest strengths that stitches has to empower consumers, particularly in a way that hasn't been achievable with other CSS-in-JS solutions in the past without a great deal of ceremony or performance impact.

Possible Solutions

As it isn't possible or feasible to require the consumer to utilize the strict methods mentioned above for CSS encapsulation, I believe providing a mechanism, even an opt-in one, to facilitate library and application developers to utilize multiple instances of stitches within a single consuming entity would be highly beneficial to the stitches community 😄

Theoretically, I believe this limitation could be resolved in a relatively passive way to consumers through good, old-fashion hashing.

Solution Litmus Test

Can multiple instances of stitches and its utilities coexist within a single consuming entity without forcing consumers to implement strict style encapsulation via shadow DOM or other similar method, as doing so isn't always possible

(borrowed from #472 in both of the following, but I'd actually be in favor of closing that issue in favor of a resolution to this discussion as I think resolving the issue described here could cover the cases described there as well)

"Simple" hashing support
Providing an optional hash parameter like the one below, that could be used to "decorate" any

• CSS custom property
• Class name
• id of the <style /> element that stitches looks to insert styles into

const { styled } = createCss({
  hash: <user-defined-hash>,

  theme: {
    colors: {
      red1: '#f00',
    }
  }
});

const Box = styled('div', {
  color: 'blue',
});

with the resulting output being

<style id="stitches-<hash>">
  :root {
    --colors-red1-<hash>: #f00;
  }
  /* unsure of where this class typically goes, but the class name itself is the only important part for this example */
  .(stitches-normal-class-name-resolution)-<hash> { color: blue; }
</style>

More Consumer Control

Providing an optional format function like the one below, that could be used to "decorate" any

• CSS custom property
• Class name
• id of the <style /> element that stitches looks to insert styles into

could allow for consumers and library developers greater flexibility in resolving the limitations noted above

const stitchesConfig = createCss({
  format: (name: string ) => `my-thing-${name}`,
});

const Box = styled('div', {
  color: 'blue',
});

with the resulting output being

<style id="my-thing-stitches">
  :root {
    --my-thing-colors-red1: #f00;
  }
  /* unsure of where this class typically goes, but the class name itself is the only important part for this example */
  .my-thing-(stitches-normal-class-name-resolution) { color: blue; }
</style>

---

I'm happy to jump on a call at your all's convenience and demo some of the behavior I've seen with issues noted above as well, I haven't spun up a demo repo yet as at least in my current use-case, I believe it might involve multiple npm package deploys 😅.

In any case, I want to reiterate that stitches has been an incredible library to work with 🥳 🙏. I'm confident that the friction points above are something that we can find a tenable, quality solution for 😄.

[dbismut]

In my case the hash solution would cover the custom insertionMethod + manual prefixing of all theme tokens.

[dylanklohr]

I went ahead and put together #536 to ease the consumer friction points noted above 😄

cc: @peduarte , @jonathantneal

[dylanklohr]

Appears resolved by #546 🥳 😄

[dbismut]

THANK YOU!

[LucasUnplugged]

I'm trying to understand how that update solves the issue.

So say I have a monorepo, and I have a package that is my component lib, including my theme and styled function. Then say I bump that package from v1.0.0 to, say, v2.0.0. I also have another package that depends on the component lib (call it, common-ui), which I update to use v2.0.0. But my app package, which depends on both of those libs, has not yet been updated to account for the breaking change, but it's updated to use the latest version of common-ui (maybe that's unlikely, but let's roll with it).

From what you were saying, I would now have 2 instances of my component lib package, so unless I update the prefix value between them, they'll still have the same issue, no?

Or do you see it as a fix precisely by using a prefix naming convention that goes with the version number?

[Kinbaum]

Hello there, this is a great discussion and sort of touches on the issue that I am having. What if on the library side, we wanted to expose its getCssString method so that it can be combined with the host's getCssString?

For example, my host application is a Next.js app that utilizes stitches. In the _document.js file, I call getCssString() to SSR my styles inside of a <style id="stitches" /> tag.

Now I have this common component that I want on every page that comes from a separate library, like a Navigation component. I want to include it's styles as well in my _document since it will be everywhere; something like this:

// _document.js
import { getCssString } from 'stitches-config';
import { getCssString as getSharedLibCssString } from 'my-shared-lib'; // This has a prefix set in its config

// ... removed for brevity 

<style id="stitches" dangerouslySetInnerHTML={ { __html: getCssString() + getSharedLibCssString() } } />

This unfortunately does not work. Additional styles are rendered once hydration happens, causing the level of precedence to change as new styles are inserted after the original declarations.

Please let me know your thoughts on this aspect.
Thanks, Matt

[dylanklohr]

👋 Hi Matt! Do you mind sharing what version of @stitches/react or @stitches/core you're using?

[Kinbaum]

Using @stitches/[email protected]

[Kinbaum]

@dylanklohr Any thoughts on this? It would be nice to have some kind of merge utility, or a configurable id vs hardcoding the value... not sure if the latter would solve the problem.

[dylanklohr]

@Kinbaum ,this is an interesting one.

I think I may be better to leave this one to @peduarte or @jonathantneal to answer, given the new CSSOM nature for client-side styling. My initial thoughts on this were that I would expect the last line of your example above to work as expected, but the precedence note intrigues me, specifically regarding how one might expect CSSOM to work client-side vs. server-side style tag rendering + hydration 🤔