From b6274f79242465ac3748f2d96b97f1e309bd45b8 Mon Sep 17 00:00:00 2001 From: Ankitsinghsisodya Date: Mon, 12 Jan 2026 10:38:38 +0530 Subject: [PATCH 1/5] docs: add processStylexRules API documentation This addresses issue #1061 by documenting the processStylexRules API that is exported from @stylexjs/babel-plugin. The documentation covers: - Function purpose and usage - Function signature with TypeScript types - Configuration options (useLayers, enableLTRRTLComments, etc.) - Example for custom bundler integrations --- .../content/docs/api/configuration/meta.json | 3 +- .../api/configuration/processStylexRules.mdx | 160 ++++++++++++++++++ packages/docs/content/docs/api/index.mdx | 2 + 3 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 packages/docs/content/docs/api/configuration/processStylexRules.mdx diff --git a/packages/docs/content/docs/api/configuration/meta.json b/packages/docs/content/docs/api/configuration/meta.json index 1c7b83fb9..b9f67322c 100644 --- a/packages/docs/content/docs/api/configuration/meta.json +++ b/packages/docs/content/docs/api/configuration/meta.json @@ -3,6 +3,7 @@ "./babel-plugin.mdx", "./eslint-plugin.mdx", "./unplugin.mdx", - "./postcss-plugin.mdx" + "./postcss-plugin.mdx", + "./processStylexRules.mdx" ] } \ No newline at end of file diff --git a/packages/docs/content/docs/api/configuration/processStylexRules.mdx b/packages/docs/content/docs/api/configuration/processStylexRules.mdx new file mode 100644 index 000000000..a4d154b5b --- /dev/null +++ b/packages/docs/content/docs/api/configuration/processStylexRules.mdx @@ -0,0 +1,160 @@ +--- +title: 'processStylexRules' +--- + +`processStylexRules` is a function exported from `@stylexjs/babel-plugin` that takes +an array of CSS rules collected during babel transformation and generates the final +CSS output. This API is useful for building custom bundler integrations or improving +existing ones. + +## Usage + +```ts +import stylexBabelPlugin from '@stylexjs/babel-plugin'; + +// Rules collected from babel transformation metadata +const rules = [ + // ... metadata.stylex from babel transform results +]; + +const css = stylexBabelPlugin.processStylexRules(rules, { + useLayers: false, + enableLTRRTLComments: false, +}); +``` + +## Function Signature + +```ts +type Rule = [ + string, // className hash + { ltr: string; rtl?: null | string }, // CSS rule object + number // priority +]; + +function processStylexRules( + rules: Array, + config?: boolean | { + useLayers?: boolean; + enableLTRRTLComments?: boolean; + legacyDisableLayers?: boolean; + useLegacyClassnamesSort?: boolean; + } +): string; +``` + +## How it works + +When StyleX compiles your JavaScript files, the babel plugin returns metadata +containing an array of CSS rule objects. You collect these rules from all files in +your project, then pass them to `processStylexRules` which: + +1. De-duplicates the rules +2. Sorts them by priority +3. Resolves `stylex.defineConsts` references +4. Generates the final CSS string + +## Configuration options + +### `useLayers` + +```ts +useLayers: boolean; // Default: false +``` + +When `true`, uses CSS `@layer` to group rules by priority level. This provides +native browser support for style priority ordering without specificity hacks. + +Example output with `useLayers: true`: +```css +@layer priority1, priority2, priority3; + +@layer priority2 { + .margin-xymmreb { margin: 10px 20px } +} + +@layer priority3 { + .backgroundColor-xrkmrrc { background-color: red } +} +``` + +--- + +### `enableLTRRTLComments` + +```ts +enableLTRRTLComments: boolean; // Default: false +``` + +When `true`, wraps LTR/RTL variants with comments instead of using attribute +selectors. Useful for post-processing with tools that can strip or swap comments +based on document direction. + +Example output with `enableLTRRTLComments: true`: +```css +/* @ltr begin */.float-x1kmio9f { float: left }/* @ltr end */ +/* @rtl begin */.float-x1kmio9f { float: right }/* @rtl end */ +``` + +Example output with `enableLTRRTLComments: false` (default): +```css +html:not([dir='rtl']) .float-x1kmio9f { float: left } +html[dir='rtl'] .float-x1kmio9f { float: right } +``` + +--- + +### `legacyDisableLayers` + +```ts +legacyDisableLayers: boolean; // Default: false +``` + +When `true`, disables the specificity polyfill (`:not(#\#)` selectors) that +StyleX uses when `useLayers` is `false`. Only use this if you have a custom +solution for handling style priority. + +--- + +### `useLegacyClassnamesSort` + +```ts +useLegacyClassnamesSort: boolean; // Default: false +``` + +When `true`, sorts rules alphabetically by className within each priority group. +When `false` (default), sorts by CSS property for more predictable output. + +## Example: Custom Bundler Integration + +```ts +import { transformAsync } from '@babel/core'; +import stylexBabelPlugin from '@stylexjs/babel-plugin'; + +// Store rules from all files +const allRules = []; + +// Transform each file +async function transformFile(code, filename) { + const result = await transformAsync(code, { + filename, + plugins: [ + [stylexBabelPlugin, { /* your options */ }] + ], + }); + + // Collect rules from metadata + if (result.metadata?.stylex?.length > 0) { + allRules.push(...result.metadata.stylex); + } + + return result.code; +} + +// After all files are processed, generate CSS +function generateCSS() { + return stylexBabelPlugin.processStylexRules(allRules, { + useLayers: true, + }); +} +``` diff --git a/packages/docs/content/docs/api/index.mdx b/packages/docs/content/docs/api/index.mdx index af7135d15..fd612153b 100644 --- a/packages/docs/content/docs/api/index.mdx +++ b/packages/docs/content/docs/api/index.mdx @@ -14,6 +14,8 @@ sidebar_position: 2 - [`@stylexjs/eslint-plugin`](/docs/api/configuration/eslint-plugin) - [`@stylexjs/unplugin`](/docs/api/configuration/unplugin) - [`@stylexjs/postcss-plugin`](/docs/api/configuration/postcss-plugin) +- [`processStylexRules`](/docs/api/configuration/processStylexRules) + ## JavaScript API From dffe26e265bc990872cca91e83186351b5dce7fc Mon Sep 17 00:00:00 2001 From: Ankitsinghsisodya Date: Mon, 12 Jan 2026 10:44:24 +0530 Subject: [PATCH 2/5] chore: trigger CLA check From 63c886ec231e4c67914b4e0a2ed8de5f765c2186 Mon Sep 17 00:00:00 2001 From: Ankitsinghsisodya Date: Mon, 12 Jan 2026 10:47:03 +0530 Subject: [PATCH 3/5] docs: add note about TypeScript definitions for useLegacyClassnamesSort --- .../content/docs/api/configuration/processStylexRules.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/docs/content/docs/api/configuration/processStylexRules.mdx b/packages/docs/content/docs/api/configuration/processStylexRules.mdx index a4d154b5b..bf5acb4ab 100644 --- a/packages/docs/content/docs/api/configuration/processStylexRules.mdx +++ b/packages/docs/content/docs/api/configuration/processStylexRules.mdx @@ -125,6 +125,11 @@ useLegacyClassnamesSort: boolean; // Default: false When `true`, sorts rules alphabetically by className within each priority group. When `false` (default), sorts by CSS property for more predictable output. +> **Note**: The `useLegacyClassnamesSort` option may not be included in the +> published TypeScript definitions for some versions of `@stylexjs/babel-plugin`. +> You can still use this option at runtime, but you may need to use a type +> assertion in your build setup until the official typings are updated. + ## Example: Custom Bundler Integration ```ts From fc61bbc57ab74319b5bcd096eeb453f55c47dba1 Mon Sep 17 00:00:00 2001 From: Ankitsinghsisodya Date: Mon, 12 Jan 2026 10:49:20 +0530 Subject: [PATCH 4/5] chore: add newline at end of file --- packages/docs/content/docs/api/configuration/meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/content/docs/api/configuration/meta.json b/packages/docs/content/docs/api/configuration/meta.json index b9f67322c..0721c7bf8 100644 --- a/packages/docs/content/docs/api/configuration/meta.json +++ b/packages/docs/content/docs/api/configuration/meta.json @@ -6,4 +6,4 @@ "./postcss-plugin.mdx", "./processStylexRules.mdx" ] -} \ No newline at end of file +} From 66a4a3363c1bf12b6832a4d2d9f233c64a3d8b4d Mon Sep 17 00:00:00 2001 From: Ankitsinghsisodya Date: Mon, 12 Jan 2026 12:29:39 +0530 Subject: [PATCH 5/5] docs: move processStylexRules to babel-plugin README Addresses review feedback: - Move documentation to babel-plugin README.md (for custom integrations) - Remove legacy Meta-internal options (enableLTRRTLComments, useLegacyClassnamesSort) - Delete standalone processStylexRules.mdx from docs site - Update navigation files (meta.json, index.mdx) --- packages/@stylexjs/babel-plugin/README.md | 116 ++++++++++++ .../content/docs/api/configuration/meta.json | 3 +- .../api/configuration/processStylexRules.mdx | 165 ------------------ packages/docs/content/docs/api/index.mdx | 1 - 4 files changed, 117 insertions(+), 168 deletions(-) delete mode 100644 packages/docs/content/docs/api/configuration/processStylexRules.mdx diff --git a/packages/@stylexjs/babel-plugin/README.md b/packages/@stylexjs/babel-plugin/README.md index dd4c926a7..450fe7df0 100644 --- a/packages/@stylexjs/babel-plugin/README.md +++ b/packages/@stylexjs/babel-plugin/README.md @@ -31,3 +31,119 @@ const result = transformSync(sourceCode, { const transformedCode = result.code; const injectedStyles = result.metadata.stylex; ``` + +## processStylexRules + +`processStylexRules` is exported from `@stylexjs/babel-plugin` and takes an array of CSS rules collected during babel transformation to generate the final CSS output. This API is useful for building custom bundler integrations. + +### Usage + +```ts +import stylexBabelPlugin from '@stylexjs/babel-plugin'; + +// Rules collected from babel transformation metadata +const rules = [ + // ... metadata.stylex from babel transform results +]; + +const css = stylexBabelPlugin.processStylexRules(rules, { + useLayers: true, +}); +``` + +### Function Signature + +```ts +type Rule = [ + string, // className hash + { ltr: string; rtl?: null | string }, // CSS rule object + number // priority +]; + +function processStylexRules( + rules: Array, + config?: boolean | { + useLayers?: boolean; + legacyDisableLayers?: boolean; + } +): string; +``` + +### How it works + +When StyleX compiles your JavaScript files, the babel plugin returns metadata +containing an array of CSS rule objects. You collect these rules from all files in +your project, then pass them to `processStylexRules` which: + +1. De-duplicates the rules +2. Sorts them by priority +3. Resolves `stylex.defineConsts` references +4. Generates the final CSS string + +### Configuration options + +#### `useLayers` + +```ts +useLayers: boolean; // Default: false +``` + +When `true`, uses CSS `@layer` to group rules by priority level. This provides +native browser support for style priority ordering without specificity hacks. + +Example output with `useLayers: true`: +```css +@layer priority1, priority2, priority3; + +@layer priority2 { + .margin-xymmreb { margin: 10px 20px } +} + +@layer priority3 { + .backgroundColor-xrkmrrc { background-color: red } +} +``` + +#### `legacyDisableLayers` + +```ts +legacyDisableLayers: boolean; // Default: false +``` + +When `true`, disables the specificity polyfill (`:not(#\#)` selectors) that +StyleX uses when `useLayers` is `false`. Only use this if you have a custom +solution for handling style priority. + +### Example: Custom Bundler Integration + +```ts +import { transformAsync } from '@babel/core'; +import stylexBabelPlugin from '@stylexjs/babel-plugin'; + +// Store rules from all files +const allRules = []; + +// Transform each file +async function transformFile(code, filename) { + const result = await transformAsync(code, { + filename, + plugins: [ + [stylexBabelPlugin, { /* your options */ }] + ], + }); + + // Collect rules from metadata + if (result.metadata?.stylex?.length > 0) { + allRules.push(...result.metadata.stylex); + } + + return result.code; +} + +// After all files are processed, generate CSS +function generateCSS() { + return stylexBabelPlugin.processStylexRules(allRules, { + useLayers: true, + }); +} +``` diff --git a/packages/docs/content/docs/api/configuration/meta.json b/packages/docs/content/docs/api/configuration/meta.json index 0721c7bf8..ad9b4558a 100644 --- a/packages/docs/content/docs/api/configuration/meta.json +++ b/packages/docs/content/docs/api/configuration/meta.json @@ -3,7 +3,6 @@ "./babel-plugin.mdx", "./eslint-plugin.mdx", "./unplugin.mdx", - "./postcss-plugin.mdx", - "./processStylexRules.mdx" + "./postcss-plugin.mdx" ] } diff --git a/packages/docs/content/docs/api/configuration/processStylexRules.mdx b/packages/docs/content/docs/api/configuration/processStylexRules.mdx deleted file mode 100644 index bf5acb4ab..000000000 --- a/packages/docs/content/docs/api/configuration/processStylexRules.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: 'processStylexRules' ---- - -`processStylexRules` is a function exported from `@stylexjs/babel-plugin` that takes -an array of CSS rules collected during babel transformation and generates the final -CSS output. This API is useful for building custom bundler integrations or improving -existing ones. - -## Usage - -```ts -import stylexBabelPlugin from '@stylexjs/babel-plugin'; - -// Rules collected from babel transformation metadata -const rules = [ - // ... metadata.stylex from babel transform results -]; - -const css = stylexBabelPlugin.processStylexRules(rules, { - useLayers: false, - enableLTRRTLComments: false, -}); -``` - -## Function Signature - -```ts -type Rule = [ - string, // className hash - { ltr: string; rtl?: null | string }, // CSS rule object - number // priority -]; - -function processStylexRules( - rules: Array, - config?: boolean | { - useLayers?: boolean; - enableLTRRTLComments?: boolean; - legacyDisableLayers?: boolean; - useLegacyClassnamesSort?: boolean; - } -): string; -``` - -## How it works - -When StyleX compiles your JavaScript files, the babel plugin returns metadata -containing an array of CSS rule objects. You collect these rules from all files in -your project, then pass them to `processStylexRules` which: - -1. De-duplicates the rules -2. Sorts them by priority -3. Resolves `stylex.defineConsts` references -4. Generates the final CSS string - -## Configuration options - -### `useLayers` - -```ts -useLayers: boolean; // Default: false -``` - -When `true`, uses CSS `@layer` to group rules by priority level. This provides -native browser support for style priority ordering without specificity hacks. - -Example output with `useLayers: true`: -```css -@layer priority1, priority2, priority3; - -@layer priority2 { - .margin-xymmreb { margin: 10px 20px } -} - -@layer priority3 { - .backgroundColor-xrkmrrc { background-color: red } -} -``` - ---- - -### `enableLTRRTLComments` - -```ts -enableLTRRTLComments: boolean; // Default: false -``` - -When `true`, wraps LTR/RTL variants with comments instead of using attribute -selectors. Useful for post-processing with tools that can strip or swap comments -based on document direction. - -Example output with `enableLTRRTLComments: true`: -```css -/* @ltr begin */.float-x1kmio9f { float: left }/* @ltr end */ -/* @rtl begin */.float-x1kmio9f { float: right }/* @rtl end */ -``` - -Example output with `enableLTRRTLComments: false` (default): -```css -html:not([dir='rtl']) .float-x1kmio9f { float: left } -html[dir='rtl'] .float-x1kmio9f { float: right } -``` - ---- - -### `legacyDisableLayers` - -```ts -legacyDisableLayers: boolean; // Default: false -``` - -When `true`, disables the specificity polyfill (`:not(#\#)` selectors) that -StyleX uses when `useLayers` is `false`. Only use this if you have a custom -solution for handling style priority. - ---- - -### `useLegacyClassnamesSort` - -```ts -useLegacyClassnamesSort: boolean; // Default: false -``` - -When `true`, sorts rules alphabetically by className within each priority group. -When `false` (default), sorts by CSS property for more predictable output. - -> **Note**: The `useLegacyClassnamesSort` option may not be included in the -> published TypeScript definitions for some versions of `@stylexjs/babel-plugin`. -> You can still use this option at runtime, but you may need to use a type -> assertion in your build setup until the official typings are updated. - -## Example: Custom Bundler Integration - -```ts -import { transformAsync } from '@babel/core'; -import stylexBabelPlugin from '@stylexjs/babel-plugin'; - -// Store rules from all files -const allRules = []; - -// Transform each file -async function transformFile(code, filename) { - const result = await transformAsync(code, { - filename, - plugins: [ - [stylexBabelPlugin, { /* your options */ }] - ], - }); - - // Collect rules from metadata - if (result.metadata?.stylex?.length > 0) { - allRules.push(...result.metadata.stylex); - } - - return result.code; -} - -// After all files are processed, generate CSS -function generateCSS() { - return stylexBabelPlugin.processStylexRules(allRules, { - useLayers: true, - }); -} -``` diff --git a/packages/docs/content/docs/api/index.mdx b/packages/docs/content/docs/api/index.mdx index fd612153b..643a085fd 100644 --- a/packages/docs/content/docs/api/index.mdx +++ b/packages/docs/content/docs/api/index.mdx @@ -14,7 +14,6 @@ sidebar_position: 2 - [`@stylexjs/eslint-plugin`](/docs/api/configuration/eslint-plugin) - [`@stylexjs/unplugin`](/docs/api/configuration/unplugin) - [`@stylexjs/postcss-plugin`](/docs/api/configuration/postcss-plugin) -- [`processStylexRules`](/docs/api/configuration/processStylexRules) ## JavaScript API