@stylexjs/postcss-plugin

Configuration options

babelConfig

babelConfig: object; // Default: {}

Options for Babel configuration. By default, the plugin reads the babel.config.js in your project. For custom configurations, set babelrc: false and specify desired options. Refer to Babel Config Options for available options.

Unless you explicitly provide babelConfig.cwd, the plugin uses its cwd option as Babel's working directory to keep config resolution consistent.

cwd

cwd: string; // Default: process.cwd()

Working directory for the plugin; defaults to process.cwd(). Dependency paths and Babel config resolution use this value.

exclude

exclude: string[] // Default: []

Array of paths or glob patterns to exclude from compilation. Paths in exclude take precedence over include.

When include is omitted, the plugin automatically excludes common build and dependency folders (for example node_modules, .next, dist, build).

importSources

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

Possible strings where you can import stylex from. Files that do not match the import sources may be skipped from being processed to speed up compilation.

When omitted, the plugin infers importSources from your @stylexjs/babel-plugin options (if present), while still keeping the default StyleX sources.

Precedence order is:

1. explicit PostCSS importSources
2. inferred from Babel config
3. built-in defaults

include

include: string[] // Default: auto-discovered

Array of paths or glob patterns to compile.

When omitted, the plugin auto-discovers source files under cwd and direct dependencies that use StyleX (checking dependencies, peerDependencies, and optionalDependencies).

useCSSLayers

useCSSLayers: boolean | {
  before?: string[],
  after?: string[],
  prefix?: string,
}; // Default: false

Enabling this option switches StyleX from using :not(#\#) to using @layer for handling CSS specificity. When set to true, each priority level is wrapped in its own @layer and a layer-ordering header is emitted. This gives StyleX CSS lower specificity than any unlayered CSS in the app (per the CSS cascade: layered styles < unlayered styles).

When your project also uses other CSS layers (e.g. 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 — extra layer names placed before StyleX's priority layers in the ordering header. Use this to ensure base layers are ordered before StyleX.
• after — extra layer names placed after StyleX's priority layers. Useful for giving a utilities layer higher precedence than StyleX.
• prefix — string prepended to every StyleX layer name (joined with .). Use this to namespace StyleX layers and avoid collisions with other frameworks (e.g. prefix: 'stylex' → stylex.priority1).

// postcss.config.js
module.exports = {
  plugins: {
    '@stylexjs/postcss-plugin': {
      useCSSLayers: {
        before: ['reset', 'base'],
        after: ['utilities'],
        prefix: 'stylex',
      },
      // ...other options
    },
  },
};

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 */
}

Debugging auto-discovery

Set STYLEX_POSTCSS_DEBUG=1 to log the resolved importSources, final include/exclude globs, and discovered dependency directories.