StyleX Unplugin Bundler Plugin

Common errors

• TypeError: Cannot read properties of undefined (reading 'webpack') at ...

  cause Attempting to use `require('@stylexjs/unplugin')` directly in a CommonJS context (e.g., Webpack config) without accessing the default export.
  fix Modify your `require` statement to `const stylexPlugin = require('@stylexjs/unplugin').default;`.

• Hot Module Replacement (HMR) for CSS is not working in development mode, or styles are not updating.

  cause Incorrect `devMode` configuration, virtual module injection issues, or missing HTML setup for dev assets.
  fix Verify `devMode: 'full'` is set in your plugin options. Ensure `<link rel="stylesheet" href="/virtual:stylex.css" />` and `import('virtual:stylex:runtime')` are correctly placed in your HTML shell or client entrypoint. Check your browser's developer console for any errors related to loading these virtual modules.

• StyleX styles are not being applied in the production build or are missing from the final CSS bundle.

  cause The bundler is not configured to emit a CSS asset, or `@stylexjs/unplugin` is not correctly integrated into the plugin chain or is misconfigured.
  fix Ensure your bundler produces at least one CSS output file (e.g., configure `MiniCssExtractPlugin` for Webpack, or rely on Vite's default CSS handling). Double-check that `stylexPlugin.<bundler-name>()` is correctly listed and configured within your bundler's plugin array.

Warnings

• gotcha When configuring the plugin in CommonJS environments (e.g., Webpack or Rspack), the default export from `@stylexjs/unplugin` must be explicitly accessed using `.default`.
  Fix: Use `const stylex = require('@stylexjs/unplugin').default;` instead of `const stylex = require('@stylexjs/unplugin');` for your bundler configuration.
• gotcha The `devMode` option (e.g., `'full'`, `'css-only'`, `'off'`) in the plugin configuration significantly impacts the development experience and Hot Module Replacement (HMR) behavior. Misconfiguration can lead to unresponsive or incomplete hot reloads.
  Fix: Review the `devMode` documentation and select the appropriate setting for your development workflow. `full` is recommended for most cases to enable HMR for both CSS and the StyleX runtime.
• gotcha Virtual modules like `virtual:stylex:runtime` and `/virtual:stylex.css` might encounter CORS issues or require specific handling in frameworks that proxy assets differently, potentially preventing proper loading during development.
  Fix: If direct HTML `<script src="/@id/virtual:stylex:runtime">` or `<link href="/virtual:stylex.css">` causes issues, consider using `import('virtual:stylex:runtime')` or `import('virtual:stylex:css-only')` from a client-side shim instead of direct HTML links.
• gotcha In Vite, packages depending on `@stylexjs/stylex` are typically auto-discovered and de-optimized. However, if your setup includes additional StyleX-consuming libraries not automatically detected, their StyleX code may not be transformed correctly.
  Fix: Use the `externalPackages` option in `stylex.vite()` to explicitly include additional dependencies that should be processed by the plugin, e.g., `externalPackages: ['your-stylex-library']`.
• gotcha The plugin is designed to append StyleX CSS to an existing CSS asset produced by your bundler. If your build setup does not generate any CSS asset, the plugin will emit a fallback `stylex.css` in the output directory.
  Fix: Ensure your bundler (e.g., Vite, Webpack with `MiniCssExtractPlugin`) is configured to produce at least one CSS output file. If not, be aware that `stylex.css` will be created as a standalone fallback.
• gotcha When using the esbuild adapter via `stylex.esbuild()`, the `metafile: true` option is a mandatory configuration for esbuild to allow the plugin to correctly locate and process CSS outputs.
  Fix: Add `metafile: true` to your `esbuild.build()` configuration when integrating `stylex.esbuild()`.

Install

• npm install stylex-unplugin npm
• yarn add stylex-unplugin yarn
• pnpm add stylex-unplugin pnpm

Imports

• stylex

  import stylex from '@stylexjs/unplugin';

  The imported `stylex` object serves as an entry point to bundler-specific functions like `stylex.vite()` or `stylex.rollup()` for ESM consumers.
• stylex (Webpack/Rspack CommonJS)
  wrong:

  const stylex = require('@stylexjs/unplugin');

  correct:

  const stylex = require('@stylexjs/unplugin').default;

  When using CommonJS environments like Webpack or Rspack, the default export of `@stylexjs/unplugin` must be explicitly accessed via `.default`.
• virtual:stylex:runtime

  import 'virtual:stylex:runtime';

  This virtual module provides the development-time HMR runtime. It is typically imported for its side effects in client-side JavaScript or linked directly in HTML as `<script type="module" src="/@id/virtual:stylex:runtime">`.
• virtual:stylex.css
  wrong:

  import 'virtual:stylex.css';

  correct:

  <link rel="stylesheet" href="/virtual:stylex.css" />

  This virtual path exposes the aggregated development CSS and should be linked directly in your HTML shell (e.g., `index.html`) for proper styling during development.

Quickstart

This quickstart demonstrates how to configure `@stylexjs/unplugin` for a Vite and React project, enabling build-time StyleX compilation and Hot Module Replacement (HMR) for development.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import stylexPlugin from '@stylexjs/unplugin';

export default defineConfig({
  plugins: [
    stylexPlugin.vite({
      // Optional: Manually include packages that use StyleX and should be transformed.
      // externalPackages: ['lib-using-stylex'],
      // devMode: 'full' // Controls HMR behavior: 'full' | 'css-only' | 'off'
    }),
    react(),
  ],
});

// To enable HMR in development, add the following to your root HTML file (e.g., public/index.html):
/*
<link rel="stylesheet" href="/virtual:stylex.css" />
<script type="module">
  import 'virtual:stylex:runtime'; // or 'virtual:stylex:css-only' if only CSS HMR is needed
</script>
*/