@stylexjs/babel-plugin

Configuration options

aliases

aliases: {[key: string]: string | Array<string>} // Default: undefined

aliases option allows you to alias project directories to absolute paths, making it easier to import modules.

Example: '@/components/*': [path.join(__dirname, './src/components/*')]

classNamePrefix

classNamePrefix: string; // Default: 'x'

Prefix to be applied to every generated className.

debug

debug: boolean; // Default: false

When true, StyleX will use debug class names and insert data-style-src props to help identify the source of the styles.

dev

dev: boolean; // Default: false

When true, StyleX will insert function calls to inject the CSS rules at runtime, making it possible to use StyleX without setting up CSS file extraction. It also enables the DOM metadata used by the StyleX Dev Tools Extension.

importSources

importSources: Array<string | { from: string; as: string }>; // Default: ['@stylexjs/stylex']

Override the package name where you can import stylex from. Used for setting up custom module aliases.

Example: importSources: ['stylex', { from: '@acme/ui', as: 'css' }]

runtimeInjection

runtimeInjection: boolean; // Default: false

Should StyleX generate code to inject styles at runtime? This may be useful during development but should be disabled in production.

styleResolution

styleResolution: // Default: 'property-specificity'
  | 'application-order'
  | 'property-specificity'

Strategy to use for merging styles.

• application-order: The last style applied wins. Consistent with how inline styles work on the web.
• property-specificity: More specific styles will win over less specific styles. Consistent with React Native. (margin-top wins over margin)

sxPropName

sxPropName: string | false; // Default: 'sx'

Customize JSX prop name for applying styles on HTML elements. Defaults to sx.

<div sx={styles.root} />

is transformed to:

<div {...stylex.props(styles.root)} />

Set this option to another string to use a different prop name, such as css. Set it to false to disable the JSX shorthand entirely.

test

test: boolean; // Default: false

When true, StyleX will only output debug classNames identifying the source of the styles.

It will not generate any styles or functional classNames. This can be useful for snapshot testing.

env

env: { [key: string]: mixed }; // Default: {}

An object of compile-time constants and functions available as stylex.env. Values are substituted before other StyleX APIs are compiled. Supports strings, numbers, objects, and functions.

treeshakeCompensation

treeshakeCompensation: boolean; // Default: false

Named imports of StyleX variables are unused after compilation. Some bundlers may remove them as dead code. Causing variables to be undefined. Enable this option to prevent that by adding an import with no specifier. (e.g. import './my-vars.stylex.js')

unstable_moduleResolution

unstable_moduleResolution: // Default: undefined
  | {
      // The module system to be used.
      // Use this value when using `ESModules`.
      type: 'commonJS',
      // The absolute path to the root directory of your project.
      // Only used as a fallback
      rootDir?: string,
      // Override `.stylex.js` with your own extension.
      themeFileExtension?: string,
    }
  | {
      // Use this when using the Haste module system
      // Where all files are imported by filename rather
      // than relative paths and all filenames must be unique.
      type: 'haste',
      // Override `.stylex.js` with your own extension.
      themeFileExtension?: string,
    }

Strategy to use for resolving variables defined with defineVars. This is required if you plan to use StyleX's theming APIs.

NOTE: While theming APIs are stable, the shape of this configuration option may change in the future.

processStylexRules

import styleXTransform from '@stylexjs/babel-plugin';

const css: string = styleXTransform.processStylexRules(rules, config);

processStylexRules takes an array of CSS rules collected from the babel plugin and returns the final CSS string. The optional config parameter controls layer wrapping and RTL handling.

config

config?:
  | boolean
  | {
      useLayers?: boolean | {
        before?: ReadonlyArray<string>;
        after?: ReadonlyArray<string>;
        prefix?: string;
      };
      enableLTRRTLComments?: boolean;
      legacyDisableLayers?: boolean;
    };

Passing true is a shorthand for { useLayers: true }.

useLayers

useLayers?: boolean | {
  before?: ReadonlyArray<string>;
  after?: ReadonlyArray<string>;
  prefix?: string;
}; // Default: false

Controls whether generated CSS is wrapped in @layer blocks for cascade ordering. When true, each priority level is placed in its own layer. When your project also uses other CSS layers (e.g. a reset layer, a design-system layer, or a utility framework like Tailwind), pass an object to position StyleX's layers relative to yours in the @layer ordering declaration and to namespace them to avoid collisions:

• before — layer names placed before StyleX layers in the ordering header.
• after — layer names placed after StyleX layers.
• prefix — string prepended to every StyleX layer name (e.g. 'stylex' → stylex.priority1).

const css = styleXTransform.processStylexRules(rules, {
  useLayers: {
    before: ['reset', 'base'],
    after: ['utilities'],
    prefix: 'stylex',
  },
});

The generated CSS begins with a layer-ordering header followed by wrapped rules:

@layer reset, base, stylex.priority1, stylex.priority2, utilities;

@layer stylex.priority1 {
  /* low-priority rules */
}
@layer stylex.priority2 {
  /* higher-priority rules */
}