@stylexswc/webpack-plugin weekly downloads statistics

@stylexswc/webpack-plugin

StyleX plugin for webpack, powered by a Rust compiler (NAPI-RS + SWC). Part of the StyleX SWC Plugin workspace.

This plugin compiles StyleX code in your webpack build with @stylexswc/rs-compiler, a Rust implementation of the StyleX transform, instead of the official Babel plugin. Your StyleX code stays exactly the same — only the build step changes, with per-file transforms 5x to 10x faster than Babel (performance). The plugin transforms your source files, collects the generated rules, and extracts them into a dedicated CSS chunk.

This is a community project and is not affiliated with Meta. It tracks the official StyleX releases (currently compatible with StyleX v0.19.1)

and requires Node.js 20 or newer. For Next.js projects, use @stylexswc/nextjs-plugin instead — it wires this plugin into the Next.js build for you.

Installation

The Rust compiler (@stylexswc/rs-compiler) is installed automatically as a dependency. Your application still needs the StyleX runtime:

Usage

Add the plugin to your webpack config:

Then import the carrier stylesheet once at the entry point of your app (e.g. index.js, App.tsx):

The plugin appends the extracted StyleX CSS to this asset during the build. Like a regular CSS file, it must flow through your CSS pipeline, so a css-loader + MiniCssExtractPlugin.loader rule (or webpack's built-in CSS support) has to cover .css files.

The carrier import is a recommendation, not a hard requirement. The plugin also appends tiny per-module CSS imports to every StyleX module, so any part of the bundle that renders a StyleX component pulls the stylesheet in on its own — most builds emit correct CSS even without the carrier. What the carrier adds is a guarantee that doesn't depend on your module graph: the stylesheet is always present and loaded with the entrypoint. That matters when something consumes StyleX output without rendering a StyleX component — plain CSS reading defineVars custom properties (var(--x…)), or injected markup carrying StyleX class names. If styles would actually be lost (no CSS asset exists to receive them at all), the plugin raises a compilation warning; it stays silent as long as the output is correct, carrier or not.

[!IMPORTANT] Migrating from 0.17.x: version 0.18.0 reworks the CSS extraction architecture. The CSS is no longer injected through auto-generated stylex.virtual.css imports — add the import '@stylexswc/webpack-plugin/stylex.css'; carrier import to your app entrypoint (recommended; see above for when you can skip it). Paths embedded in module identifiers are now relative to compiler.context, which changes chunk hashes once and makes builds reproducible across machines.

Plugin Options

Basic Options

rsOptions

• Type: Partial • Optional • Description: StyleX compiler options passed to @stylexswc/rs-compiler. For the standard options, see the official StyleX documentation.

[!NOTE] The include and exclude options are exclusive to the Rust compiler and are not available in the official StyleX Babel plugin.

rsOptions.include

• Type: (string | RegExp)[] • Optional • Description: Glob patterns or regular expressions selecting the files to transform. When specified, only files matching at least one pattern are transformed. Patterns are matched against paths relative to the current working directory.

rsOptions.exclude

• Type: (string | RegExp)[] • Optional • Description: Glob patterns or regular expressions excluding files from the transform. A file matching any exclude pattern is skipped even if it matches an include pattern. Patterns are matched against paths relative to the current working directory.

stylexImports

• Type: Array • Default: ['stylex', '@stylexjs/stylex'] • Description: Specifies where StyleX is imported from. Supports both string paths and import aliases.

useCSSLayers

• Type: boolean • Default: false • Description: Wraps the generated CSS in cascade layers for better style isolation.

nextjsMode

• Type: boolean • Default: false • Description: Enables Next.js-specific optimizations and compatibility features. Leave off unless the plugin is driven by the Next.js integration.

extractCSS

• Type: boolean • Optional • Default: true • Description: Controls whether the generated CSS is extracted into a separate file.

loaderOrder

• Type: 'first' | 'last' • Optional • Default: 'first' • Description: When the StyleX transformation runs relative to other webpack loaders. • 'first' (recommended): StyleX processes the source code before any other loaders run. Automatically enables injectStylexSideEffects so tree-shaking cannot remove .stylex and .consts imports. • 'last': StyleX processes after all other loaders have completed. Use this if other loaders (TypeScript, SWC plugins) must transform your code before StyleX sees it.

Why 'first' is recommended: after StyleX rewrites your code, imports from .stylex and .consts files can look unused to subsequent loaders and bundler passes and get tree-shaken away:

With loaderOrder: 'first', the plugin preserves these imports by injecting side-effect imports automatically.

stylexPackages

• Type: string[] • Optional • Default: ['@stylexjs/'] • Description: node_modules is excluded from the transform by default, even for files that reference a StyleX import. Packages that ship untransformed StyleX source (component libraries, token packages) must be allowlisted here with path fragments:

carrierCss

Path to a custom carrier stylesheet that receives the extracted StyleX CSS — the file you import once at your app entrypoint. Absolute, or relative to compiler.context. Replaces the default @stylexswc/webpack-plugin/stylex.css carrier: useful when another file named stylex.css in your project would collide with the default filename pattern, or when you want the carrier to live in your own source tree.…

Description from the npm listing.