RFC: Maintain variable names for keys that start with "--"

[nmn]

RFC - Variable name literals for keys that that start with "--"

The main change proposed is to opt out of automatic variable name generation when the object keys used within stylex.defineVars starts with --.

Motivations

1. Using variables across StyleX and global .css files

There is often a desire to use variables defined within StyleX to be usable within a raw CSS file to set global styles. However, since the actual generated variable names created by StyleX are unknown until compile time, this process isn't developer friendly.

The only escape hatch today is to fallback to strings for using variables within StyleX and CSS. This means losing all the benefits provided by StyleX's theming APIs, such as type-safety and guaranteed default values.

2. Migrating from CSS strings to StyleX theming APIs

There existing codebases that use CSS variable names as strings today and don't have a clear migration path to adopt StyleX's theming APIs. While it is easier to move to StyleX's APIs for new variables, it is usually a non-starter to migrate existing variables. This new feature provides an escape hatch to make migration possible.

A typical migration process might look like:

1. Define all existing CSS variables as literals with a stylex.defineVars call with the default value set to null
2. Update all usages of that variable to use the object created with stylex.defineVars
3. Define the default values for the variables within StyleX
4. Define any Themes within StyleX
5. Delete the old patterns for defining the variables to make StyleX the exclusive way to define variables.
6. Optionally, if no uses of the variables exist outside of StyleX anymore, rename the keys to drop the --.

Caveat

There is one major caveat or risk of this proposal. Unlike variables generated by StyleX itself, there is no way to guarantee that a variable name isn't accidentally duplicated. If the same variable name is used in two separate stylex.defineVars calls, it will result in the same variable being defined twice in the generated CSS file.

Ideally, in a follow-up, we should be able to detect such a conflict at compile time.

[github-actions[bot]]

compressed-size: runtime library

Size change: 0.00 kB Total size: 2.52 kB

View unchanged

| Filename: gzip (minify) | kB size | kB change | % change | | :--- | :--- | :--- | :--- | | `./packages/stylex/lib/stylex.js` | **1.04** (3.22) | **0.00** (0.00) | **0.0%** (0.0%) | | `./packages/stylex/lib/StyleXSheet.js` | **1.48** (3.75) | **0.00** (0.00) | **0.0%** (0.0%) |

[github-actions[bot]]

compressed-size: e2e bundles

Size change: 0.00 kB Total size: 1128.74 kB

View unchanged

| Filename: gzip (minify) | kB size | kB change | % change | | :--- | :--- | :--- | :--- | | `./apps/rollup-example/.build/bundle.js` | **1005.32** (10185.35) | **0.00** (0.00) | **0.0%** (0.0%) | | `./apps/rollup-example/.build/stylex.css` | **123.42** (774.34) | **0.00** (0.00) | **0.0%** (0.0%) |