Registry / web-framework / stylex-unplugin

stylex-unplugin

library0.17.6jsnpmunverified

@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.

web-framework devops

npm install stylex-unplugin

package ↗

INSTALL

IMPORT

SIG · STYLEX-UNPLUGIN

stylex-unplugin

web-frameworkjavascriptv0.17.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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)

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

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

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

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

✗ import '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.

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> */

Debug

Known issues

gotchaWhen 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.

affects: >=0.1.0

gotchaThe `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.

affects: >=0.1.0

gotchaVirtual 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.

affects: >=0.1.0

gotchaIn 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']`.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

gotchaWhen 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()`.

affects: >=0.1.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

0.17.6latest on npm

Audit

Dependencies

unpluginrequiredRequired as a peer dependency for the universal plugin abstraction that @stylexjs/unplugin is built upon.

Agent activity

12 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/stylex-unplugin ↗