### Install Dependencies and Build Project

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Clone the repository, install project dependencies using pnpm, and build all packages. This is a standard setup for contributing to the project.

```bash
git clone https://github.com/Dwlad90/stylex-swc-plugin.git

pnpm install

pnpm build

pnpm test
```

--------------------------------

### Install @stylexswc/playwright

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/playwright/README.md

Install the package as a development dependency.

```bash
npm install --save-dev @stylexswc/playwright
```

--------------------------------

### Install Turbopack Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/turbopack-plugin/README.md

Install the Turbopack plugin for StyleX SWC. Ensure `@stylexswc/rs-compiler` is also installed.

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

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

--------------------------------

### Input StyleX Code Example

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

A basic example demonstrating how to define styles and props using StyleX.

```typescript
import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  root: {
    padding: 10,
  },
  element: {
    backgroundColor: 'red',
  },
});

const styleProps = stylex.props(styles.root, styles.element);
```

--------------------------------

### Install @stylexswc/design-system

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/design-system/README.md

Use this command to add the design system package to your project. This package is private and intended for internal use.

```bash
pnpm add @stylexswc/design-system
```

--------------------------------

### Install NAPI-RS Compiler

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Ensure the NAPI-RS compiler for StyleX is installed if not already present.

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

--------------------------------

### Install Next.js Plugin for StyleX

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Install the necessary plugin for Next.js projects to enable StyleX compilation.

```bash
# For Next.js projects
npm install --save-dev @stylexswc/nextjs-plugin
```

--------------------------------

### Configure Webpack with StylexPlugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Integrate the StylexPlugin into your Webpack configuration to enable StyleX transformations. This example shows basic setup with output path and filename configuration.

```javascript
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({
      filename: 'styles.[contenthash].css',
      dev: argv.mode === 'development',
    }),
  ],
  cache: true,
});

module.exports = config;
```

--------------------------------

### Install PostCSS Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/postcss-plugin/README.md

Install the PostCSS plugin using npm for development.

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

--------------------------------

### Example StyleX SWC Plugin Configuration

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

A comprehensive example of configuring the StyleX SWC Webpack plugin. Includes options for development mode, path inclusion/exclusion, StyleX imports, CSS layers, and custom CSS transformation.

```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,
      },
    }),
  ],
};
```

--------------------------------

### Run Development Server

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/nextjs-postcss-example/README.md

Use these commands to start the development server for the Next.js project. Open http://localhost:3000 in your browser to view the result.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
pnpm dev
```

```bash
bun dev
```

--------------------------------

### Install Rollup Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Install the StyleX SWC Rollup plugin as a development dependency.

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

--------------------------------

### Example Configuration with rsOptions

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/unplugin/README.md

Configure the StyleX SWC plugin with `rsOptions` to specify build-related settings such as development mode, include/exclude paths, and other StyleX compiler options.

```typescript
// vite.config.ts
import StylexRsPlugin from '@stylexswc/unplugin/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    StylexRsPlugin({
      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__/**'],
      },
      useCSSLayers: true,
      useCssPlaceholder: true,
    }),
  ],
});
```

--------------------------------

### Install StyleX RS Compiler

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Command to install the StyleX RS Compiler package as a development dependency.

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

--------------------------------

### Development Environment Setup and Commands

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Utilize the Makefile for common development tasks. This includes setting up the environment, building packages, running development servers, and executing tests and quality checks.

```bash
make setup

make help

make build

make dev

make test

make quick-check
```

--------------------------------

### Path Filtering Examples

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Demonstrates various ways to configure path filtering using `include` and `exclude` options within `rsOptions`.

```APIDOC
## 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.*'],
  },
})
```
```

--------------------------------

### StyleX Plugin Configuration

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Example of how to configure the StyleX SWC Webpack plugin with various options.

```APIDOC
## StyleX Plugin Configuration

### Description
This section details the configuration options available for the StyleX SWC Webpack plugin.

### `transformCss` Option

- **Description**: A custom CSS transformation function. Use this to apply PostCSS or other CSS transformations after the plugin injects CSS.
- **Type**: `(css: string, filePath: string | undefined) => string | Buffer | Promise<string | Buffer>`
- **Optional**: Yes

### `cacheGroup` Option

- **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.
- **Type**: `CacheGroupOptions` (webpack cache group configuration)
- **Optional**: Yes

**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,
      },
    }),
  ],
};
```
```

--------------------------------

### Install @stylexswc/jest Package

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/jest/README.md

Install the Jest transformer package as a development dependency.

```bash
npm install --save-dev @stylexswc/jest
```

--------------------------------

### Install Unplugin for Other Build Tools

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Install the unplugin for integrating StyleX compilation with other build tools like Vite or Webpack.

```bash
# For other build tools
npm install --save-dev @stylexswc/unplugin
```

--------------------------------

### Example of a custom theme SWC plugin configuration

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Demonstrates configuring a custom theme SWC plugin with its WASM path and specific theme options within the `transform` function.

```typescript
transform(filename, code, {
  dev: true,
  swcPlugins: [
    [
      '/Users/me/plugins/swc_plugin_theme.wasm',
      {
        themeName: 'theme-name',
        themeConfig: {
          primaryColor: 'blue',
          spacing: 8,
        },
      },
    ],
  ],
});
```

--------------------------------

### Next.js CSS Transformation Example

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/postcss-plugin/README.md

Example of transforming CSS using PostCSS and autoprefixer within Next.js configuration when using the StyleX plugin.

```javascript
/// next.config.js

//...other code
transformCss: async css => {
  const postcss = require('postcss');
  const result = await postcss([require('autoprefixer')]).process(css);
  return result.css;
},
//...other code
```

--------------------------------

### Example of use_real_file_for_source option

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Shows how to configure the StyleX SWC plugin to use actual source files for error reporting and source maps.

```typescript
transform(filename, code, {
  use_real_file_for_source: true, // Use actual source files (default)
  dev: true,
  // ... other options
});
```

--------------------------------

### Configure PostCSS

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/postcss-plugin/README.md

Configure the PostCSS setup to include the StyleX plugin with specific file inclusions.

```javascript
module.exports = {
  plugins: {
    '@stylexswc/postcss-plugin': {
      include: ['src/**/*.{js,jsx,ts,tsx}'],
    },
    autoprefixer: {},
  },
};
```

--------------------------------

### Run Storybook Development Server

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/example-storybook/README.md

Starts the Storybook development server for component exploration and live editing. Accessible at http://localhost:6006.

```bash
npm run storybook
# or
yarn storybook
# or
pnpm storybook
```

--------------------------------

### Manage Package Dependencies

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/guidelines/SCRIPTS.md

Install all dependencies, or add/remove specific dependencies for a targeted package using pnpm with the `--filter` flag.

```sh
pnpm install                                              # install all
```

```sh
pnpm add --filter=@stylexswc/<package-name> <dep>         # add
```

```sh
pnpm remove --filter=@stylexswc/<package-name> <dep>      # remove
```

--------------------------------

### Configure Webpack with StyleX Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Integrate the StyleXPlugin into your Webpack configuration. This example includes a custom CSS transformation using PostCSS and Autoprefixer.

```javascript
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;
```

--------------------------------

### Include Specific Directories with Glob Patterns

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/turbopack-plugin/README.md

Use 'include' to specify directories or files that should be processed. This example includes files from 'app' and 'components' directories.

```typescript
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.tsx': {
          loaders: ['@stylexswc/turbopack-plugin/loader'],
          options: {
            rsOptions: {
              include: ['app/**/*.{ts,tsx}', 'components/**/*.{ts,tsx}'],
            },
          },
        },
      },
    },
  },
};

export default nextConfig;
```

--------------------------------

### Configure Jest Transformer

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/jest/README.md

Add the @stylexswc/jest transformer to your Jest configuration file. This example shows how to pass StyleX compiler options.

```javascript
const path = require('path');

module.exports = {
  transform: {
    '^.+\.(ts|tsx|js|jsx|mjs|cjs|html)$': [
      '@stylexswc/jest',
      {
        rsOptions: {
          aliases: {
            '@/*': [path.join(__dirname, '*')],
          },
          unstable_moduleResolution: {
            type: 'commonJS',
          },
        },
      },
    ],
  },
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jsdom',
};
```

--------------------------------

### Run the CLI for Parsing Tests

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-test-parser/README.md

Execute the CLI tool to parse tests. Ensure the official StyleX repository is cloned nearby or updated. This command filters for the test-parser package and starts the parsing process.

```bash
pnpm --filter=@stylexswc/test-parser start
```

--------------------------------

### StyleX Plugin: Include specific packages from node_modules

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Combines `include` and `exclude` options to precisely control which files are transformed. This example includes StyleX-related files from `node_modules` while excluding test files.

```javascript
stylexPlugin({
  rsOptions: {
    include: [
      'src/**/*.{ts,tsx,js,jsx}',
      'node_modules/@stylexjs/open-props/**/*.js',
    ],
    exclude: ['**/*.test.*'],
  },
})
```

--------------------------------

### Configure Jest with StyleX SWC Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/jest/README.md

This configuration sets up Jest to use `jest-chain-transform` which orchestrates multiple transformers, including `@stylexswc/jest` and `@swc/jest`. Ensure all necessary packages are installed.

```javascript
// jest.config.js
const nextJest = require('next/jest');
const path = require('path');

const createJestConfig = nextJest({
  dir: process.cwd(),
});

const customJestConfig = {
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  testEnvironment: 'jsdom',
  transform: {
    '^.+\.(ts|tsx|js|jsx|mjs|cjs|html)$': [
      'jest-chain-transform',
      {
        transformers: [
          [
            '@stylexswc/jest',
            {
              rsOptions: {
                aliases: {
                  '@/*': [path.join(__dirname, '*')],
                },
                unstable_moduleResolution: {
                  type: 'commonJS',
                },
              },
            },
          ],
          [
            '@swc/jest',
            {
              $schema: 'https://json.schemastore.org/swcrc',
              jsc: {
                parser: {
                  syntax: 'typescript',
                  tsx: true,
                  dynamicImport: true,
                  decorators: true,
                  dts: true,
                },
                transform: {
                  react: {
                    useBuiltins: true,
                    runtime: 'automatic',
                  },
                },
                target: 'esnext',
                loose: false,
                externalHelpers: false,
                keepClassNames: true,
                baseUrl: './',
                paths: {
                  '@/*': ['./*'],
                },
              },
              module: {
                type: 'es6',
              },
              minify: false,
            },
          ],
        ],
      },
    ],
  },
};

module.exports = customJestConfig;
```

--------------------------------

### Turbopack Configuration with StyleX Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/nextjs-plugin/README.md

Configure the StyleX SWC plugin for Turbopack. This setup is similar to Webpack but uses the `withStylexTurbopack` function. Ensure `rsOptions` are correctly set for path aliases.

```typescript
import path from 'path';
import withStylexTurbopack from '@stylexswc/nextjs-plugin/turbopack';

const rootDir = __dirname;

export default withStylexTurbopack({
  // Add any StyleX options here
  rsOptions: {
    dev: process.env.NODE_ENV !== 'production',
    aliases: {
      '@/*': [path.join(rootDir, '*')],
    },
    unstable_moduleResolution: {
      type: 'commonJS',
    },
  },
  stylexImports: ['@stylexjs/stylex'],
})({
  transpilePackages: ['@stylexjs/open-props'],
  experimental: {
    turbopack: {
      // Additional Turbopack configuration if needed
    },
  },
  // Optionally, add any other Next.js config below
});
```

--------------------------------

### StyleX Plugin: Include specific directories

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Use the `include` option within `rsOptions` to specify glob patterns for files that should be transformed by the StyleX compiler. This example targets TypeScript and JavaScript files in the 'src' directory.

```javascript
stylexPlugin({
  rsOptions: {
    include: ['src/**/*.{ts,tsx,js,jsx}'],
  },
})
```

--------------------------------

### Convenience Entry Point

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-styleq/README.md

The `styleq` function serves as a convenience entry point. It utilizes default options and a newly created cache for merging style inputs.

```APIDOC
## `styleq`

### Description
A convenience entry point that uses the default options and a freshly-constructed cache.

### Signature
`styleq(&[StyleqInput<V>]) -> StyleqResult<V>`

### Parameters
- `inputs`: An array of `StyleqInput<V>` representing the style objects to merge.

### Returns
- `StyleqResult<V>`: An object containing the merged `class_name`, `inline_style`, and `data_style_src`.
```

--------------------------------

### Run Tests and Benchmarks

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-styleq/README.md

Execute tests and benchmarks for the stylex-styleq package using pnpm.

```sh
pnpm run --filter=@stylexswc/stylex-styleq test
pnpm run --filter=@stylexswc/stylex-styleq bench
```

--------------------------------

### Type Check a Specific Package

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/CLAUDE.md

This command performs type checking for a designated package. Ensure pnpm is installed and configured.

```bash
pnpm run --filter=@stylexswc/<package-name> typecheck
```

--------------------------------

### StyleX Compiler Output JSON

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Example of the JSON output from the StyleX compiler, including transformed code, metadata, and source map.

```json
{
  "code": "import * as stylex from '@stylexjs/stylex';\nexport const styles = {\n    default: {\n        backgroundColor: \"xrkmrrc\",\n        color: \"xju2f9n\",\n        $$css: true\n    }\n};\n",
  "metadata": {
    "stylex": {
      "styles": [
        [
          "xrkmrrc",
          {
            "ltr": ".xrkmrrc{background-color:red}",
            "rtl": null
          },
          3000
        ],
        [
          "xju2f9n",
          {
            "ltr": ".xju2f9n{color:blue}",
            "rtl": null
          },
          3000
        ]
      ]
    }
  },
  "map": "{\"version\":3,\"sources\":[\"<anon>\"],\"names\":[],\"mappings\":\"AACE;AACA;;;;;;EAKG\"}"
}
```

--------------------------------

### Build All Packages with pnpm

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Use this command to build all packages in the project when not using the Makefile.

```bash
pnpm build
```

--------------------------------

### Run Formatting Check Post Action

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/CLAUDE.md

Execute this command to check code formatting after the main action. pnpm is required.

```bash
pnpm format:check
```

--------------------------------

### Build Static Storybook for Production

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/example-storybook/README.md

Generates a static build of the Storybook for deployment. The output is placed in the 'storybook-static/' directory.

```bash
npm run build
# or
pnpm build
```

--------------------------------

### Button Component Visual Test Suite

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/playwright/README.md

A complete example of a visual test suite for a Button component, including tests for default and hover states.

```typescript
import { test, expect } from '@stylexswc/playwright';

test.describe('Button component', () => {
  test('renders in default state', async ({ page, screenshotOptions }) => {
    await page.goto('/components/button');
    await expect(page).toHaveScreenshot(
      'button-default.png',
      screenshotOptions
    );
  });

  test('renders in hover state', async ({ page, screenshotOptions }) => {
    await page.goto('/components/button');
    await page.hover('button');
    await expect(page).toHaveScreenshot('button-hover.png', screenshotOptions);
  });
});
```

--------------------------------

### Define Global Styles with StyleX Marker

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/unplugin/README.md

Create a CSS file and add the `@stylex;` marker to indicate where StyleX generated CSS should be injected. This file should then be imported into your application's entry point.

```css
/* global.css */
:root {
  --brand-color: #663399;
}

body {
  margin: 0;
  font-family: system-ui, sans-serif;
}

@stylex;
```

--------------------------------

### Enable Trace Logging (Bash/Zsh)

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Set the STYLEX_DEBUG environment variable to 'trace' for the most verbose output, useful for deep debugging. Run this before your development command.

```bash
STYLEX_DEBUG=trace npm run dev
```

--------------------------------

### Apply CSS Reset with StyleX

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/webpack-unplugin-example/public/index.html

This CSS reset is designed for use with StyleX and Webpack. It sets up fundamental styles for a consistent starting point across browsers.

```css
/* 1. Use a more-intuitive box-sizing model */
*, 
*::before, 
*::after { box-sizing: border-box; }

/* 2. Remove default margin */
* { margin: 0; }

body {
  /* 3. Add accessible line-height */
  line-height: 1.5;
  /* 4. Improve text rendering */
  -webkit-font-smoothing: antialiased;
}

/* 5. Improve media defaults */
img, picture, video, canvas, svg { display: block; max-width: 100%; }

/* 6. Inherit fonts for form controls */
input, button, textarea, select { font: inherit; }

/* 7. Avoid text overflows */
p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; }

/* 8. Improve line wrapping */
p { text-wrap: pretty; }
h1, h2, h3, h4, h5, h6 { text-wrap: balance; }

/* 9. Create a root stacking context */
#root, #__next { isolation: isolate; }
```

--------------------------------

### Create StyleQ Instance

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-styleq/README.md

The `create_styleq` function allows for the creation of a long-lived `Styleq` instance with a persistent cache and customizable options.

```APIDOC
## `create_styleq`

### Description
Builds a long-lived `Styleq` instance with a persistent cache and custom options.

### Signature
`create_styleq(options) -> Styleq<V>`

### Parameters
- `options`: `StyleqOptions` struct containing configuration like `disable_cache`, `disable_mix`, `dedupe_class_name_chunks`, and `transform`.

### Returns
- `Styleq<V>`: A `Styleq` instance configured with the provided options and a persistent cache.
```

--------------------------------

### Exclude Test and Build Files with Glob Patterns

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/turbopack-plugin/README.md

Use 'exclude' to prevent specific files or directories from being processed. This example excludes test files and the 'dist' directory.

```typescript
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.tsx': {
          loaders: ['@stylexswc/turbopack-plugin/loader'],
          options: {
            rsOptions: {
              exclude: ['**/*.test.*', '**/*.spec.*', '**/dist/**'],
            },
          },
        },
      },
    },
  },
};

export default nextConfig;
```

--------------------------------

### Build the CLI Application

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-test-parser/README.md

Compile the release version of the CLI app using pnpm. This command filters for the test-parser package and runs the build script.

```bash
pnpm --filter=@stylexswc/test-parser run build
```

--------------------------------

### Import CSS File in Entry Point

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/unplugin/README.md

Import the CSS file containing the StyleX marker into your main application file (e.g., `src/main.ts`). This ensures the styles are processed by the plugin.

```typescript
// src/main.ts
import './global.css';
import { App } from './App';
```

--------------------------------

### Custom Cache Group Configuration

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Example of overriding default cache group parameters for StyleX CSS extraction. Customize chunk naming, priority, or other split chunks options.

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

--------------------------------

### Run Tests with pnpm

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Execute all tests in the project using pnpm. This is an alternative to `make test`.

```bash
pnpm test
```

--------------------------------

### Example of StyleX Import Tree-Shaking Issue

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Illustrates how StyleX imports might be removed by tree-shaking if the loader order is not set to 'first'. This is automatically handled when `loaderOrder: 'first'` is used.

```typescript
// 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 } };
```

--------------------------------

### Enable Debug Logging (Windows Command Prompt)

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-rs-compiler/README.md

Use the 'set' command to define the STYLEX_DEBUG environment variable for Windows Command Prompt. This enables debug logging for the build process.

```cmd
set STYLEX_DEBUG=debug && npm run build
```

--------------------------------

### Run Root-Level Build Commands

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/guidelines/SCRIPTS.md

Execute build, test, lint, and format commands across all packages in the monorepo using Turbo. Ensure Node.js version is >=20 and pnpm version is >=10.

```sh
pnpm build           # build all packages
```

```sh
pnpm test            # run all tests
```

```sh
pnpm lint            # lint all packages
```

```sh
pnpm lint:check      # lint with JSON report output
```

```sh
pnpm format          # format TS/MD files (prettier)
```

```sh
pnpm format:check    # check formatting without changes
```

```sh
pnpm test:visual     # Playwright visual regression (all apps)
```

```sh
pnpm typecheck       # TypeScript type checking
```

--------------------------------

### StyleX RS CSS Reset with Vite

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/vite-unplugin-placeholder-css-example/index.html

Applies a comprehensive CSS reset using StyleX RS within a Vite project. Ensure StyleX is properly configured in your Vite setup.

```css
/* 1. Use a more-intuitive box-sizing model */
*, *::before, *::after { box-sizing: border-box; }
/* 2. Remove default margin */
* { margin: 0; }
body {
  /* 3. Add accessible line-height */
  line-height: 1.5;
  /* 4. Improve text rendering */
  -webkit-font-smoothing: antialiased;
}
/* 5. Improve media defaults */
img, picture, video, canvas, svg { display: block; max-width: 100%; }
/* 6. Inherit fonts for form controls */
input, button, textarea, select { font: inherit; }
/* 7. Avoid text overflows */
p, h1, h2, h3, h4, h5, h6 { overflow-wrap: break-word; }
/* 8. Improve line wrapping */
p { text-wrap: pretty; }
h1, h2, h3, h4, h5, h6 { text-wrap: balance; }
/* 9. Create a root stacking context */
#root, #__next { isolation: isolate; }
```

--------------------------------

### Build StyleX Test Parser Crate

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-test-parser/README.md

Executes the command to build the StyleX test parser crate. This is a fundamental step for development and testing.

```bash
make crate-test-parser-build
```

--------------------------------

### Path Filtering with Regular Expressions

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/turbopack-plugin/README.md

Configure 'include' and 'exclude' using regular expressions for more precise path matching. This example includes .tsx files in 'app' and 'components', and excludes test and stories files.

```typescript
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.tsx': {
          loaders: ['@stylexswc/turbopack-plugin/loader'],
          options: {
            rsOptions: {
              include: [/app\/.*\.tsx$/, /components\/.*\.tsx$/],
              exclude: [/\.test\./, /\.stories\./],
            },
          },
        },
      },
    },
  },
};

export default nextConfig;
```

--------------------------------

### Update Visual Snapshots Locally

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/playwright/README.md

Update visual snapshots for your current OS using the pnpm test:visual command.

```bash
pnpm test:visual -- --update-snapshots
```

--------------------------------

### Update Visual Snapshots with Docker

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/playwright/README.md

Use Docker commands to update, run, or check visual snapshots, ensuring CI-equivalent Linux snapshots.

```bash
pnpm test:visual:update up
pnpm test:visual:update run
pnpm test:visual:update check
```

--------------------------------

### StyleX Plugin: Exclude test and build files

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/rollup-plugin/README.md

Utilize the `exclude` option within `rsOptions` to prevent StyleX transformation on specified files. This example excludes files matching '*.test.*', '*.spec.*', and any files within '**/dist/**'.

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

--------------------------------

### Webpack Configuration with StyleX Plugin

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/nextjs-plugin/README.md

Configure the StyleX SWC plugin within your Webpack setup. Use `transformCss` for custom CSS transformations like PostCSS. Ensure `rsOptions` are correctly set for path inclusion and exclusion.

```javascript
const path = require('path');
const stylexPlugin = require('@stylexswc/nextjs-plugin');
const rootDir = __dirname;

module.exports = stylexPlugin({
  // Add any StyleX options here
  rsOptions: {
    dev: process.env.NODE_ENV !== 'production',
    // Include only specific directories
    include: [
      'app/**/*.{ts,tsx}',
      'components/**/*.{ts,tsx}',
      'src/**/*.{ts,tsx}',
    ],
    // Exclude test files and API routes
    exclude: ['**/*.test.*', '**/*.stories.*', '**/__tests__/**', 'app/api/**'],
    aliases: {
      '@/*': [path.join(rootDir, '*')],
    },
    unstable_moduleResolution: {
      type: 'commonJS',
    },
  },
  stylexImports: ['@stylexjs/stylex', { from: './theme', as: 'tokens' }],
  useCSSLayers: true,
  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;
  },
})(
  {
    transpilePackages: ['@stylexjs/open-props'],
    // Optionally, add any other Next.js config below
  }
);
```

--------------------------------

### Run Testing Post Action

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/CLAUDE.md

Use this command to run tests after the main action has been completed. pnpm is the package manager.

```bash
pnpm test
```

--------------------------------

### Path Filtering: Transform Only Specific Packages from Node Modules

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/unplugin/README.md

Use both `include` and `exclude` options in `rsOptions` to precisely control which files are processed. This example includes specific StyleX related packages from `node_modules` while excluding test files.

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

--------------------------------

### Format Code with pnpm

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Automatically format all code in the project using pnpm. This is an alternative to `make format`.

```bash
pnpm format
```

--------------------------------

### Check Formatting for a Specific Package

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/CLAUDE.md

Run this command to verify code formatting using Prettier for a selected package. pnpm must be used.

```bash
pnpm run --filter=@stylexswc/<package-name> format:check
```

--------------------------------

### Generate StyleX Test Parser Documentation

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/crates/stylex-test-parser/README.md

Generates documentation for the StyleX test parser crate. This command is useful for creating up-to-date documentation for the project.

```bash
make crate-test-parser-docs
```

--------------------------------

### Configure Rust Linker Settings for MacOS

Source: https://github.com/dwlad90/stylex-swc-plugin/wiki/Rust-Linker-Error-MacOS

Add this configuration to `~/.cargo/config.toml` to fix linking errors on MacOS, supporting both Intel and Apple Silicon architectures.

```toml
[target.x86_64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]

[target.aarch64-apple-darwin]
rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",
]
```

--------------------------------

### Run Snapshot Tests

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/apps/example-storybook/README.md

Executes unit tests with snapshot testing to verify component output. Use 'test:update' to update snapshots after intentional changes.

```bash
npm run test
# or
pnpm test
```

```bash
npm run test:update
# or
pnpm test:update
```

--------------------------------

### Combined Include and Exclude with Precedence

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/webpack-plugin/README.md

Demonstrates how to use both `include` and `exclude` options, where `exclude` rules take precedence over `include` rules.

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

--------------------------------

### Configure Next.js with Webpack

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/nextjs-plugin/README.md

Use the default import for standard Next.js Webpack builds. Pass StyleX options and Next.js configuration.

```javascript
const stylexPlugin = require('@stylexswc/nextjs-plugin');

module.exports = stylexPlugin({
  // StyleX options here
})({
  // Next.js config here
});
```

--------------------------------

### Path Filtering: Combined Include and Exclude

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/unplugin/README.md

Demonstrates how to use both `include` and `exclude` options in `rsOptions` simultaneously. The `exclude` rules take precedence, allowing for fine-grained control over file processing.

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

--------------------------------

### Run Visual Regression Tests with pnpm

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Specifically run visual regression tests using pnpm. This command is equivalent to `make test-visual`.

```bash
pnpm test:visual
```

--------------------------------

### StyleX Compiler Options: Include Specific Files

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/packages/jest/README.md

Use the `include` option within `rsOptions` to specify glob patterns or regular expressions for files to be transformed by the StyleX compiler.

```javascript
{
  rsOptions: {
    include: ['src/**/*.{ts,tsx}', 'app/**/*.{ts,tsx}'],
  },
}
```

--------------------------------

### Generate Docs for Rust Transform Crate

Source: https://github.com/dwlad90/stylex-swc-plugin/blob/develop/README.md

Generates documentation for the 'transform' Rust crate. This command targets a specific Rust crate's documentation generation action.

```bash
make crate-transform-docs
```