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 1c7b83fb9..ad9b4558a 100644 --- a/packages/docs/content/docs/api/configuration/meta.json +++ b/packages/docs/content/docs/api/configuration/meta.json @@ -5,4 +5,4 @@ "./unplugin.mdx", "./postcss-plugin.mdx" ] -} \ No newline at end of file +} diff --git a/packages/docs/content/docs/api/index.mdx b/packages/docs/content/docs/api/index.mdx index af7135d15..643a085fd 100644 --- a/packages/docs/content/docs/api/index.mdx +++ b/packages/docs/content/docs/api/index.mdx @@ -15,6 +15,7 @@ sidebar_position: 2 - [`@stylexjs/unplugin`](/docs/api/configuration/unplugin) - [`@stylexjs/postcss-plugin`](/docs/api/configuration/postcss-plugin) + ## JavaScript API - [`stylex.create()`](/docs/api/javascript/create)