{"id":15838,"library":"stylex-unplugin","title":"StyleX Unplugin Bundler Plugin","description":"@stylexjs/unplugin is a universal bundler plugin built upon the `unplugin` abstraction, designed to compile StyleX CSS at build time. It aggregates CSS from all transformed modules within a project and injects the resulting styles into an existing CSS asset produced by the bundler. If no such asset is found, it emits a stable fallback CSS file. Currently at version 0.17.6, the package is actively maintained and supports various bundlers including Vite, Rollup, Webpack, Rspack, and esbuild. Its key differentiators lie in providing a unified, declarative API across these diverse build environments, ensuring consolidated and deterministic StyleX output. Furthermore, it offers specialized development helpers via virtual modules like `virtual:stylex:runtime` and `/virtual:stylex.css` to facilitate efficient hot CSS reloads during development, simplifying the integration of StyleX into modern JavaScript build pipelines.","status":"active","version":"0.17.6","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","stylex","css","unplugin","vite","rollup","webpack","rspack","typescript"],"install":[{"cmd":"npm install stylex-unplugin","lang":"bash","label":"npm"},{"cmd":"yarn add stylex-unplugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add stylex-unplugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for the universal plugin abstraction that @stylexjs/unplugin is built upon.","package":"unplugin","optional":false}],"imports":[{"note":"The imported `stylex` object serves as an entry point to bundler-specific functions like `stylex.vite()` or `stylex.rollup()` for ESM consumers.","symbol":"stylex","correct":"import stylex from '@stylexjs/unplugin';"},{"note":"When using CommonJS environments like Webpack or Rspack, the default export of `@stylexjs/unplugin` must be explicitly accessed via `.default`.","wrong":"const stylex = require('@stylexjs/unplugin');","symbol":"stylex (Webpack/Rspack CommonJS)","correct":"const stylex = require('@stylexjs/unplugin').default;"},{"note":"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\">`.","symbol":"virtual:stylex:runtime","correct":"import 'virtual:stylex:runtime';"},{"note":"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.","wrong":"import 'virtual:stylex.css';","symbol":"virtual:stylex.css","correct":"<link rel=\"stylesheet\" href=\"/virtual:stylex.css\" />"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport stylexPlugin from '@stylexjs/unplugin';\n\nexport default defineConfig({\n  plugins: [\n    stylexPlugin.vite({\n      // Optional: Manually include packages that use StyleX and should be transformed.\n      // externalPackages: ['lib-using-stylex'],\n      // devMode: 'full' // Controls HMR behavior: 'full' | 'css-only' | 'off'\n    }),\n    react(),\n  ],\n});\n\n// To enable HMR in development, add the following to your root HTML file (e.g., public/index.html):\n/*\n<link rel=\"stylesheet\" href=\"/virtual:stylex.css\" />\n<script type=\"module\">\n  import 'virtual:stylex:runtime'; // or 'virtual:stylex:css-only' if only CSS HMR is needed\n</script>\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Use `const stylex = require('@stylexjs/unplugin').default;` instead of `const stylex = require('@stylexjs/unplugin');` for your bundler configuration.","message":"When configuring the plugin in CommonJS environments (e.g., Webpack or Rspack), the default export from `@stylexjs/unplugin` must be explicitly accessed using `.default`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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']`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add `metafile: true` to your `esbuild.build()` configuration when integrating `stylex.esbuild()`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Modify your `require` statement to `const stylexPlugin = require('@stylexjs/unplugin').default;`.","cause":"Attempting to use `require('@stylexjs/unplugin')` directly in a CommonJS context (e.g., Webpack config) without accessing the default export.","error":"TypeError: Cannot read properties of undefined (reading 'webpack') at ..."},{"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.","cause":"Incorrect `devMode` configuration, virtual module injection issues, or missing HTML setup for dev assets.","error":"Hot Module Replacement (HMR) for CSS is not working in development mode, or styles are not updating."},{"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.","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.","error":"StyleX styles are not being applied in the production build or are missing from the final CSS bundle."}],"ecosystem":"npm"}