npm package: @stylexswc/webpack-plugin
Description: StyleX webpack plugin with NAPI-RS compiler
Latest version: 0.15.3

# Webpack plugin with NAPI-RS StyleX compiler integration

> Part of the [StyleX SWC Plugin](https://github.com/Dwlad90/stylex-swc-plugin#readme) workspace

`Webpack plugin` for an unofficial
[`napi-rs`](https://github.com/dwlad90/stylex-swc-plugin/tree/develop/crates/stylex-rs-compiler)
compiler that includes the StyleX SWC code transformation under the hood.

## Installation

To install the package, run the following command:

```bash
npm install --save-dev @stylexswc/webpack-plugin
```

Please install `@stylexswc/rs-compiler` if you haven't done so already:

```bash
npm install --save-dev @stylexswc/rs-compiler
```

## Usage

Modify Webpack config. For example:

```js
const StylexPlugin = require('@stylexswc/webpack-plugin');
const path = require('path');

const config = (env, argv) => ({
  entry: {
    main: './js/index.js',
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js',
  },
  plugins: [
    new StylexPlugin({
      // ... Other StyleX options
      transformCss: async (css, filePath) => {
        const postcss = require('postcss');
        const result = await postcss([require('autoprefixer')]).process(css, {
          from: filePath,
          map: {
            inline: false,
            annotation: false,
          },
        });
        return result.css;
      },
    }),
  ],
  cache: true,
});

module.exports = config;
```

## Plugin Options

### Basic Options

#### `rsOptions`

- Type: `Partial<StyleXOptions>`
- Optional
- Description: StyleX compiler options that will be passed to the NAPI-RS compiler.
  For standard StyleX options, see the [official StyleX documentation](https://stylexjs.com/docs/api/configuration/babel-plugin/).

> [!NOTE]
> **New Features:** The `include` and `exclude` options are exclusive to this NAPI-RS compiler implementation and are not available in the official StyleX Babel plugin.

##### `rsOptions.include`

- Type: `(string | RegExp)[]`
- Optional
- Description: **RS-compiler Only** An array of glob patterns or regular expressions to include specific files for StyleX transformation.
  When specified, only files matching at least one of these patterns will be transformed.
  Patterns are matched against paths relative to the current working directory.

##### `rsOptions.exclude`

- Type: `(string | RegExp)[]`
- Optional
- Description: **RS-compiler Only** An array of glob patterns or regular expressions to exclude specific files from StyleX transformation.
  Files matching any of these patterns will not be transformed, even if they match an `include` pattern.
  Patterns are matched against paths relative to the current working directory.

#### `stylexImports`

- Type: `Array<string | { as: string, from: string }>`
- Default: `['stylex', '@stylexjs/stylex']`
- Description: Specifies where StyleX will be imported from. Supports both
  string paths and import aliases.

#### `useCSSLayers`

- Type: `boolean`
- Default: `false`
- Description: Enables CSS cascade layers support for better style isolation.

#### `nextjsMode`

- Type: `boolean`
- Default: `false`
- Description: Enables Next.js-specific optimizations and compatibility
  features.

#### `extractCSS`

- Type: `boolean`
- Optional
- Default: `true`
- Description: Controls whether CSS should be extracted into a separate file

#### `loaderOrder`

- Type: `'first' | 'last'`
- Optional
- Default: `'first'`
- Description: Determines when the StyleX transformation is applied relative to other webpack loaders.
  - `'first'` (recommended): StyleX processes the source code before any other loaders run.
    Automatically enables `injectStylexSideEffects` to prevent tree-shaking from removing `.stylex` and `.consts` imports.
  - `'last'`: StyleX processes after all other loaders have completed.
    Use this if you need other loaders (like TypeScript or SWC plugins) to transform your code before StyleX processing.

  **Why `'first'` is recommended:**
  When StyleX transforms your code first, imports from `.stylex` and `.consts` files may appear unused to subsequent loaders/bundlers and get removed by tree-shaking. The plugin automatically injects side-effect imports to prevent this issue.

  **Example of the problem:**
  ```ts
  // Before transformation
  import { colors } from './theme.stylex';
  const styles = stylex.create({
    root: { backgroundColor: colors.primary }
  });

  // After StyleX transformation (appears unused to bundler)
  import { colors } from './theme.stylex';  // ← May be tree-shaken!
  const styles = { root: { backgroundColor: 'x1a2b3c', $$css: true } };
  ```

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

### Advanced Options

#### `transformCss`

- Type:
  `(css: string, filePath: string | undefined) => string | Buffer | Promise<string | Buffer>`
- Optional
- Description: Custom CSS transformation function. Since the plugin injects CSS
  after all loaders, use this to apply PostCSS or other CSS transformations.

#### `cacheGroup`

- Type: `CacheGroupOptions` (webpack cache group configuration)
- Optional
- Description: Allows overriding the default webpack cache group parameters for StyleX CSS extraction.
  By default, the plugin creates a dedicated cache group named `stylex` for extracted StyleX CSS.
  Use this option to customize cache group behavior such as chunk naming, priority, or other split chunks options.

**Default cache group configuration:**
```javascript
{
  name: 'stylex',
  test: /\.stylex\.virtual\.css$/,
  type: 'css/mini-extract',
  chunks: 'all',
  enforce: true,
}
```

**Example - Custom cache group:**
```javascript
new StylexPlugin({
  cacheGroup: {
    name: 'my-stylex-bundle',
    chunks: 'initial',
    priority: 20,
    enforce: true,
  },
})
```

### Example Configuration

```javascript
const StylexPlugin = require('@stylexswc/webpack-plugin');

module.exports = {
  plugins: [
    new StylexPlugin({
      rsOptions: {
        dev: process.env.NODE_ENV !== 'production',
        // Include only specific directories
        include: ['src/**/*.{ts,tsx}', 'components/**/*.{ts,tsx}'],
        // Exclude test files and stories
        exclude: ['**/*.test.*', '**/*.stories.*', '**/__tests__/**'],
      },
      stylexImports: ['@stylexjs/stylex', { from: './theme', as: 'tokens' }],
      useCSSLayers: true,
      nextjsMode: false,
      loaderOrder: 'first', // Process before other loaders (default)
      transformCss: async css => {
        const postcss = require('postcss');
        const result = await postcss([require('autoprefixer')]).process(css);
        return result.css;
      },
      // Optional: Override cache group settings
      cacheGroup: {
        name: 'stylex',
        priority: 30,
      },
    }),
  ],
};
```

#### Path Filtering Examples

**Include only specific directories:**

```javascript
new StylexPlugin({
  rsOptions: {
    include: ['src/**/*.tsx', 'app/**/*.tsx'],
  },
})
```

**Exclude test and build files:**

```javascript
new StylexPlugin({
  rsOptions: {
    exclude: ['**/*.test.*', '**/*.spec.*', '**/dist/**', '**/node_modules/**'],
  },
})
```

**Using regular expressions:**

```javascript
new StylexPlugin({
  rsOptions: {
    include: [/src\/.*\.tsx$/],
    exclude: [/\.test\./, /\.stories\./],
  },
})
```

**Combined include and exclude (exclude takes precedence):**

```javascript
new StylexPlugin({
  rsOptions: {
    include: ['src/**/*.{ts,tsx}'],
    exclude: ['**/__tests__/**', '**/__mocks__/**'],
  },
})
```

**Exclude node_modules except specific packages:**

```javascript
new StylexPlugin({
  rsOptions: {
    // Exclude all node_modules except @stylexjs/open-props
    exclude: [/node_modules(?!\/@stylexjs\/open-props)/],
  },
})
```

**Transform only specific packages from node_modules:**

```javascript
new StylexPlugin({
  rsOptions: {
    include: [
      'src/**/*.{ts,tsx}',
      'node_modules/@stylexjs/open-props/**/*.js',
      'node_modules/@my-org/design-system/**/*.js',
    ],
    exclude: ['**/*.test.*'],
  },
})
```

## Documentation

- [StyleX Documentation](https://stylexjs.com)
- [NAPI-RS compiler for StyleX](https://github.com/Dwlad90/stylex-swc-plugin/tree/develop/crates/stylex-rs-compiler)

## Acknowledgments

This plugin was inspired by
[`stylex-webpack`](https://github.com/SukkaW/stylex-webpack).