Feature Request: Customize (or remove entirely) hash on css variables.

[nicksrandall]

Hello!

I thought I would document my use-case and see if there is any interest in supporting it within Vanilla Extract. If so, I'm happy to send in some PRs.

I'm building a set a reusable components that will be consumed by several different applications. All of these components are using vanilla-extract for css and they pull variables in from a "global theme". Because all these components are using vanilla-extact, getting access to the css variable names is easy.

However, the "host" applications that will be consuming these components have not migrated to using vanilla extract -- but they would still like to use some of the variables from the global theme in their hand-written, vanilla CSS. Because of the randomized hash that gets added to the CSS vars, the task of looking up these variable names is cumbersome. I wondering if it would be possible to create an API where the hash could be over-written or removed entirely.

What I'm thinking is that I would like to pass in an optional second param to createThemeContract that would define the hash that is to be used by all the variable names created by that contract. I could potentially pass "" to denote that I would not like a hash at all.

Are the maintainers of this library open to this change? If so, any guidance on how the API should look?

P.S. I know about the DEBUG ids -- I think what I asking for is different but could potentially conflict with that feature.

[markdalgleish]

If you don't want to use hashed variables, you can just write them by hand:

export const globalVars = {
  brandColor: 'var(--brand-color)'
};

Setting a var:

import { style } from '@vanilla-extract/css';
import { globalVars } from './vars.css';

export const themeClass = style({
  vars: {
    [globalVars.brandColor]: 'pink'
  }
});

Consuming a var:

import { style } from '@vanilla-extract/css';
import { globalVars } from './vars.css';

export const root = style({
  background: globalVars.brandColor
});

There may be an official API for this in the future, but this will work in the meantime.

[nicksrandall]

Thanks Mark.

For posterity, what I ended up doing is writing my own (slightly modified) version of createThemeContract.

import { walkObject, MapLeafNodes, CSSVarFunction } from "@vanilla-extract/private";
import cssesc from 'cssesc';

type NullableTokens = {
  [key: string]: string | NullableTokens | null;
};

type ThemeVars<ThemeContract extends NullableTokens> = MapLeafNodes<
  ThemeContract,
  CSSVarFunction
>

// This will create a theme contrat without a hash so it's easier to use
// in raw css.
function createThemeContract<ThemeTokens extends NullableTokens>(
  tokens: ThemeTokens,
  namespace: string,
): ThemeVars<ThemeTokens> {
  return walkObject(tokens, (_value, path) => {
    const varName = path.join("-");
    const cssVarName = cssesc(varName.match(/^[0-9]/) ? `_${varName}` : varName, {
      isIdentifier: true,
    });
    return `var(--${namespace}-${cssVarName})` as const;
  });
}

This way, my css vars are name-spaced but also predictable so they can easily be consumed in hand-written css files if needed.

PS. It would be nice if NullableTokens and ThemeVars was exported by the @vanilla-extract/css module so that I didn't have to re-implement them for this use case. I'll send a PR (#315).

[markdalgleish]

We're thinking this might actually be worth including in the core library as createGlobalThemeContract.

Its basic usage would look like this:

import { createGlobalThemeContract } from '@vanilla-extract/css';

export const vars = createGlobalThemeContract({
  color: {
    blue: 'color-blue',
    green: 'color-green',
    red: 'color-red',
  },
});

If you want to apply a prefix, you could provide a map function as the 2nd argument:

import { createGlobalThemeContract } from '@vanilla-extract/css';

export const vars = createGlobalThemeContract({
  color: {
    blue: 'color-blue',
    green: 'color-green',
    red: 'color-red',
  },
}, (value) => `prefix-${value}`);

If you want to automatically generate names from the object keys, as you've done, the map function would also be passed the path as an array:

import { createGlobalThemeContract } from '@vanilla-extract/css';

export const vars = createGlobalThemeContract({
  color: {
    blue: null,
    green: null,
    red: null,
  },
}, (_, path) => `prefix-${path.join('-')}`);

[nicksrandall]

I like this. It would work for our use-case.

[nicksrandall]

I wrote a PR for this #319

[mrwest808]

We have a different (albeit possibly quite rare) use case that would benefit from being able to customize the hash function, where different versions of our component library can be consumed on the same page, and would need to have unique class/var names based on either CSS content or package version to avoid style collisions between usages.

Historically we have simply used the generateScopedName option from postcss-modules to achieve this, and it has worked out decently.

Simply having an optional option to provide a custom hash function would solve this for us, i.e. something like this:

plugins: [
  vanillaExtractPlugin({ hash: customHashFunction  })
]

While testing @vanilla-extract/css together with the Vite plugin in our component library monorepo, I circumvented this "issue" by creating a local package with a custom hash function, and added a Yarn resolution that pointed @emotion/hash to that package instead.

{
  "resolutions": {
    "**/@emotion/hash": "file:./packages/hash"
  }
}

This is of course just a hack that isn't scalable and relies on implementation details in @vanilla-extract/css, but it was an interesting exploration.

[roblotter]

I'd also love access to the hash function - to make generated classNames even shorter