Request: help making a working Vite template

[BMCwebdev]

Continuing from #1043

I would like to help out and make a template for Vite builds using the Babel/PostCSS method, but I still keep hitting a wall. When trying to create a Vite app that needs to run the compiler on some packages in node modules (much like the old open-props examples) I will get the Unexpected 'stylex.defineVars' call at runtime. Styles must be compiled by '@stylexjs/babel-plugin'. error.

Does anyone have a working Vite example, that uses the PostCSS method, and also compiles a library like open-props?

I can achieve this with HoursGoul's plugin: https://github.com/HorusGoul/vite-plugin-stylex

But looking at the plugin, I cannot tell what is happening in there that allows this to work and yet not work in the PostCSS configuration.

I hope it is not too presumptuous for me to try an pull some smart people into this thread, but I'll ask your forgiveness ahead of time!
@sergiocarneiro to continue our conversation from the other thread.
@zaydek because I see you very active in HorusGoul's repo.
@HorusGoul the man himself.

Thanks all.

[BMCwebdev]

Here's what our robot overloads had to say. Strap in.

Deep Dive into vite-plugin-stylex: Enabling StyleX Compilation in node_modules for Vite Applications

1. Introduction

StyleX, a CSS-in-JS library open-sourced by Meta, offers a build-time approach to generating atomic CSS, aiming for type safety and performance.¹ It integrates into JavaScript and TypeScript projects primarily through a Babel plugin. Vite has emerged as a leading frontend build tool, prized for its fast development server and optimized build outputs, largely due to its use of native ES modules during development and esbuild for pre-bundling dependencies.²

A significant challenge arises when attempting to use StyleX within dependencies located in node_modules in a Vite-based React application. Vite's default behavior of pre-bundling dependencies can interfere with StyleX's compilation process, which needs to operate on the original source code of these libraries. The vite-plugin-stylex (specifically the HorusGoul/vite-plugin-stylex fork, as it is the subject of the user query) aims to resolve this by orchestrating Vite's behavior and the StyleX compilation process.

This report provides an in-depth analysis of vite-plugin-stylex, examining its source code concepts and GitHub issues to understand its mechanisms for enabling StyleX compilation within node_modules. It will detail why this plugin can succeed where manual PostCSS, Babel, and Vite configurations might falter, explore aspects that are difficult to replicate manually, and discuss the plugin's context within the broader ecosystem of StyleX tooling.

2. Understanding StyleX and Vite's Default Behavior

To appreciate the role of vite-plugin-stylex, it is essential to first understand the core tenets of StyleX and how Vite typically handles node_modules.

2.1. StyleX Fundamentals

StyleX is designed as a build-time CSS-in-JS library. This means that style definitions written in JavaScript or TypeScript are processed during the build, resulting in static CSS files and optimized runtime code.¹ The cornerstone of this process is the @stylexjs/babel-plugin, which traverses the code, identifies StyleX API calls (like stylex.create() and stylex.props()), generates atomic CSS rules, and replaces the StyleX calls with optimized runtime instructions (typically CSS class names).¹

A key feature for theming and cross-file/package style resolution in StyleX is the unstable_moduleResolution option within the Babel plugin configuration. This option, particularly its rootDir parameter, is crucial for StyleX to correctly resolve theme variables and other style definitions imported from different files or packages.⁴ When processing files from node_modules, the rootDir must be set to the root directory of the specific external library being compiled to ensure its internal StyleX imports resolve correctly.

2.2. Vite's node_modules Handling and Extensibility

Vite employs an intelligent strategy for handling dependencies from node_modules to accelerate its development server startup and optimize browser performance. By default, Vite pre-bundles these dependencies using esbuild.² This pre-bundling serves two primary purposes:

1. Compatibility: It converts CommonJS (CJS) and Universal Module Definition (UMD) modules into native ES Modules (ESM), which Vite serves to the browser during development.⁶
2. Performance: It can combine ESM dependencies that consist of many internal modules into single, more manageable modules, reducing the number of HTTP requests the browser needs to make.⁶

However, this pre-bundling process transforms the original source code of the dependencies. For a build-time CSS-in-JS library like StyleX, which relies on its Babel plugin to parse the original StyleX API calls, this pre-bundled code is unsuitable. The StyleX constructs would have already been processed or potentially stripped by esbuild.

To address scenarios where pre-bundling is undesirable, Vite provides the optimizeDeps.exclude configuration option.⁶ Listing a dependency in optimizeDeps.exclude instructs Vite to skip the esbuild pre-bundling step for that particular package. This means the browser will receive the dependency's code closer to its original form, allowing other Vite plugins to process it. This exclusion is a fundamental prerequisite for any plugin aiming to transform source code within node_modules.

Vite's plugin system is highly extensible, offering various hooks that allow plugins to intervene at different stages of the build and development process. Key hooks include config (to modify Vite's configuration), resolveId (to customize module resolution), load (to provide custom module content), and transform (to modify the content of modules).¹¹ These hooks are the building blocks that vite-plugin-stylex utilizes.

3. Deep Dive into vite-plugin-stylex (HorusGoul/vite-plugin-stylex)

The HorusGoul/vite-plugin-stylex plugin is designed to bridge the gap between StyleX's compilation needs and Vite's default behaviors, particularly concerning external libraries residing in node_modules.

3.1. Core Architecture and Mechanisms

The primary objective of vite-plugin-stylex is to enable the @stylexjs/babel-plugin to correctly process not only the application's source code but also the source code of specified dependencies from node_modules that use StyleX.

The core strategy involves several coordinated steps:

1. Bypassing Pre-bundling: The plugin ensures that Vite does not pre-bundle the StyleX-based libraries from node_modules. This is achieved by leveraging the libraries option provided by the plugin.
2. Targeted Transformation: It uses Vite's transform hook to intercept JavaScript/TypeScript files. For files belonging to the application or the specified external libraries, it invokes the @stylexjs/babel-plugin.
3. CSS Aggregation and Injection: The CSS generated by the Babel plugin from all processed files (application and libraries) is collected and made available to the application, typically through a virtual CSS module.

The libraries Option:

This configuration option is central to the plugin's functionality for node_modules. When a user specifies package names in the libraries array (e.g., libraries: ['cool-stylex-package']), the plugin adds these package names to Vite's internal optimizeDeps.exclude list.13 As noted in the plugin's documentation, @stylexjs/open-props is included by default.13 This exclusion is critical because it ensures that the source code of these libraries is not pre-bundled by esbuild, thereby making it available in its original form for the StyleX Babel plugin to process during the transform phase. Without this step, the StyleX constructs within the library code would not be accessible for compilation.

Interaction with @stylexjs/babel-plugin:

The vite-plugin-stylex acts as an orchestrator for @stylexjs/babel-plugin. It ensures that the Babel plugin is invoked with the correct configuration for files within node_modules. This includes passing standard StyleX options like importSources (which defaults to ['stylex', '@stylexjs/stylex'] but can be customized, for instance, for react-strict-dom 4).

More critically, for StyleX theming and module resolution to work correctly within external libraries, the unstable_moduleResolution.rootDir option for @stylexjs/babel-plugin must be dynamically set to the root directory of the specific library being processed. A global rootDir pointing to the main project's root would lead to incorrect resolution for imports within the dependency. The vite-plugin-stylex must infer or resolve the correct rootDir for each file originating from a different package in the libraries list. This dynamic, context-aware configuration of the Babel plugin is a sophisticated aspect of vite-plugin-stylex and is vital for the proper functioning of StyleX features like defineVars across package boundaries.⁵

CSS Output Management:

As @stylexjs/babel-plugin processes files, it generates CSS rules and metadata. vite-plugin-stylex collects this CSS output from both the application's source files and the processed node_modules libraries. This aggregated CSS is then typically exposed to the Vite application through a virtual module (e.g., import 'virtual:stylex.css') or by handling specific CSS import patterns (e.g., import './stylex.css?url' or an @stylex stylesheet; directive in a CSS file) that the plugin resolves and loads.11 This mechanism ensures that all StyleX-generated styles are consolidated and injected into the application.

The following table summarizes the key configuration options of HorusGoul/vite-plugin-stylex relevant to node_modules processing:

Table 1: HorusGoul/vite-plugin-stylex - Key Configuration for node_modules

Option	Type	Default (if known/inferred)	Description	Impact on node_modules Processing	Snippet(s)
libraries	string	['@stylexjs/open-props']	List of package names from node_modules that use StyleX and need compilation.	Crucially, adds these packages to Vite's optimizeDeps.exclude list, preventing pre-bundling and allowing the plugin's transform hook to process their source with @stylexjs/babel-plugin.	13
importSources	`(string \	{ from: string, as: string })`	['stylex', '@stylexjs/stylex']	Specifies StyleX import identifiers for the Babel plugin.	Ensures StyleX calls within node_modules libraries (using potentially varied import aliases) are correctly identified and transformed by @stylexjs/babel-plugin.
unstable_moduleResolution	object	{ type: 'commonJS', rootDir: process.cwd() } (from nonzzz/vite-plugin-stylex, likely similar for HorusGoul if not overridden per library)	Configuration for StyleX's Babel plugin to resolve theme modules and other internal dependencies.	For node_modules, rootDir needs to be dynamically set by the plugin to the specific library's root path to ensure correct StyleX theming and asset resolution within that library.	4
stylexVirtualModuleId (Conceptual name for virtual CSS)	string	e.g., virtual:stylex.css or handled via *.css?url / @stylex stylesheet;	The mechanism for injecting aggregated StyleX CSS.	Collects CSS generated from both app code and specified node_modules libraries into a single, manageable CSS asset.	11

This comparison underscores that vite-plugin-stylex encapsulates a significant amount of specialized logic needed to make StyleX work seamlessly with external libraries in a Vite environment.

5. Hard-to-Replicate Aspects of vite-plugin-stylex

Several aspects of vite-plugin-stylex's functionality would be particularly challenging to replicate reliably in a manual setup:

• Orchestration of Vite's Build Pipeline for node_modules: The precise interaction with optimizeDeps.exclude and ensuring that transformations occur at the correct stage in Vite's plugin lifecycle for these non-pre-bundled node_modules is a delicate process. It requires a deep understanding of Vite's internal plugin ordering and dependency processing logic.¹¹ Getting this timing wrong could lead to either untransformed code or errors.
• Robust Dynamic Path Resolution for @stylexjs/babel-plugin: As previously emphasized, the capability to dynamically and accurately set unstable_moduleResolution.rootDir for the StyleX Babel plugin, based on the origin of each file being processed (whether from the main application or one of several different node_modules dependencies), is a sophisticated piece of logic. This involves resolving package boundaries and file paths correctly, which can be particularly complex in scenarios like monorepos or when using linked dependencies. The need for absolute file paths for StyleX's alias setup to support theming correctly further highlights the importance of precise path resolution, which the plugin automates.¹⁴ This dynamic contextualization of the Babel plugin is arguably the most difficult feature to replicate manually.
• Seamless CSS Aggregation and Virtual Module Management: The process of collecting CSS outputs from numerous transformation operations (across the application and multiple libraries), ensuring correct ordering (especially if CSS layers are used via the useCSSLayers option), and managing this aggregated CSS through a virtual module that integrates with Vite's serving and HMR capabilities is non-trivial. Dedicated CSS injection plugins for Vite, like vite-plugin-lib-inject-css, demonstrate that even this focused task requires careful handling of Vite's metadata and hooks such as renderChunk.¹⁹ vite-plugin-stylex must perform this CSS management in addition to the upstream Babel transformation.
• Ensuring HMR Compatibility for Styles from External Libraries: Implementing Hot Module Replacement that works reliably for style changes originating within node_modules dependencies (which have been excluded from optimizeDeps) is complex. It requires the plugin to monitor these files for changes, re-trigger their StyleX compilation, update the aggregated CSS content of the virtual module, and then correctly signal Vite to inject only the updated styles into the browser, all without losing application state.
• Error Handling and Diagnostics: A well-constructed plugin can provide more informative error messages when StyleX compilation fails within a dependency. It can contextualize the error to the specific library and file, which would be much harder to achieve in a generic manual Babel setup that lacks this awareness of processing node_modules.

These elements represent significant engineering effort encapsulated within the plugin, abstracting away considerable complexity from the end-user.

6. Context, Alternatives, and Future Considerations

The vite-plugin-stylex by HorusGoul exists within an evolving ecosystem for StyleX tooling.

• Status and Maintenance of HorusGoul/vite-plugin-stylex: The plugin's README indicates it is in "early development".¹³ Observations of its GitHub repository (last commit activity being several months ago as of late 2023/early 2024 and issue fix: missing variable name in API Doc #99 questioning its status with StyleX 0.10) raise concerns about its current maintenance level and long-term viability.¹³
• Related Plugins:
  • nonzzz/vite-plugin-stylex: This earlier unofficial plugin is now marked as "No longer maintained Migrate to stylex-extend".²¹ Its options, such as optimizedDeps for handling external libraries and unstable_moduleResolution ⁴, show that similar architectural approaches were employed.
  • @stylex-extend/vite: Presented as the successor to nonzzz/vite-plugin-stylex ²², this plugin also features an optimizedDeps option, indicating it tackles the same core problem of processing external StyleX files. It represents a more current alternative if HorusGoul/vite-plugin-stylex is indeed unmaintained.
• The Official StyleX PostCSS Plugin (@stylexjs/postcss-plugin): A significant development is the release of an official PostCSS plugin by the StyleX team. Their documentation states: "StyleX now ships with an all-new PostCSS plugin. This plugin allows you to use StyleX with any PostCSS-compatible toolchain... The PostCSS plugin is now our recommended approach for using StyleX in a Next.js or Vite project".⁵ This official recommendation signals a potential shift in integration strategy. Vite has robust built-in PostCSS support.²³ Utilizing @stylexjs/postcss-plugin could leverage Vite's native capabilities more directly, potentially simplifying the toolchain by reducing reliance on more deeply integrated, Vite-specific plugins that manipulate the build process at multiple levels. However, the specifics of how this PostCSS plugin, when used via Vite's PostCSS pipeline, would handle the node_modules processing (particularly the optimizeDeps.exclude requirement and the dynamic rootDir for StyleX's Babel plugin which the PostCSS plugin would wrap) would need careful consideration. It's plausible that manual configuration of optimizeDeps.exclude might still be necessary, as PostCSS plugins themselves don't typically alter Vite's dependency optimization behavior. The PostCSS plugin essentially moves the StyleX Babel transformation into the PostCSS processing stage.
• Challenges with External Libraries in General: The difficulties in processing styles from external libraries are not unique to StyleX. For example, an issue reported for vanilla-extract (another CSS-in-JS library) described rendering errors when consuming components from an external library, with suggestions that the bundling of the UI library itself might be a factor.²⁵ This indicates a broader pattern: build-time CSS-in-JS solutions often require careful coordination between how libraries are authored/bundled and how consuming applications are configured to process them.

7. Conclusion and Strategic Recommendations

vite-plugin-stylex (specifically the HorusGoul/vite-plugin-stylex version) effectively addresses a critical challenge for developers wishing to use StyleX-based component libraries from node_modules within a Vite application. Its core mechanism—leveraging Vite's optimizeDeps.exclude to prevent pre-bundling of specified dependencies and then applying the @stylexjs/babel-plugin via Vite's transform hook with context-aware configurations (like dynamic rootDir)—is a sound architectural approach. This significantly simplifies the developer experience compared to the daunting complexity of a manual setup.

The plugin successfully automates several hard-to-replicate aspects, most notably the dynamic configuration of the StyleX Babel plugin for individual node_modules dependencies and the aggregation of CSS from disparate sources into a manageable output with HMR support.

Guidance for Developers:

• When using HorusGoul/vite-plugin-stylex or similar plugins, meticulous configuration of the libraries (or equivalent optimizedDeps) option is paramount to ensure all external StyleX dependencies are correctly processed.
• The maintenance status of any third-party plugin is a crucial consideration. Given the questions around HorusGoul/vite-plugin-stylex's current activity ¹³, developers should evaluate alternatives like @stylex-extend/vite ²² or, more significantly, the official @stylexjs/postcss-plugin.⁵
• For troubleshooting, developers should familiarize themselves with Vite's dependency optimization logging (e.g., using vite --debug) and utilize tools like vite-plugin-inspect ¹¹ to understand the transformation pipeline and intermediate states of modules.

Strategic Recommendation:

The StyleX team's endorsement of their @stylexjs/postcss-plugin as the recommended approach for Vite integration is a strong signal.5 For new projects or those with the capacity to refactor their build setup, evaluating this official PostCSS plugin is advisable. This aligns with official guidance and may offer better long-term stability and compatibility. However, this approach might shift some of the complexity towards correctly configuring Vite's PostCSS pipeline to process node_modules (potentially still requiring manual optimizeDeps.exclude settings and ensuring the StyleX Babel plugin options are correctly passed through PostCSS).

If a higher level of abstraction is preferred and a plugin like vite-plugin-stylex (or its actively maintained forks/successors like @stylex-extend/vite) "just works" for a given project's needs and its maintenance status is deemed acceptable, it remains a valuable tool for its simplification of a complex integration task. The choice depends on the project's specific requirements, tolerance for managing build complexities, and preference for official versus community-driven solutions.

[sergiocarneiro]

Let's iterate on this. I prepared a reproduction for this issue with my setup:

https://github.com/sergiocarneiro/example-stylex-vite-packages

[idonov]

Please a fix for this, I am in the same boat

[BMCwebdev]

I’m continuing to work on this. I’ll take a look at your repo @sergiocarneiro.

On my end I am making changes to my component library. Currently it is a hybrid approach:

• Hybrid Bundling: Code is bundled into single files per format (ES and UMD)
• Partial Externalization: Core dependencies like React and StyleX are kept external
• Internal Bundling: Utilities like FontAwesome and React Aria Toast components are bundled with the library
• Output Structure: Generates single files (library.es.js, library.umd.js) rather than preserving source structure

I am going to move to a transpile only build and move all currently bundled dependencies into peerdependencies.

I think there is a use case to be able to use the approach I have been employing, but I want to see if this resolves my issues.

[sergiocarneiro]

@BMCwebdev On my repo, I tried removing all the dependencies that used StyleX, and only apply it on the app itself, and the issue still occurred.

[dd-jonas]

I was using a vite-plugin-stylex-dev setup, but this is no longer working in 0.13.0. I tried many different ways to set up the postcss plugin, but I got none of them working. I've been looking at examples all over the discussions and issues, but there isn't a proper explanation anywhere.

@nmn The way the postcss installation is documented right now is broken for me (https://stylexjs.com/docs/learn/installation/#postcss). More specifically, I'm getting the error Support for the experimental syntax 'flow' isn't currently enabled. I followed the steps by installing the babel and postcss plugin, and added the postcss plugin to my postcss.config.js file. I don't have a babel config file in my project, but as far as I can tell from the docs I shouldn't need it if I use the postcss plugin.

[nmn]

Please share a reproduction. This is likely a small configuration issue.

[sergiocarneiro]

Hey guys, I might have found the ideal solution for a Vite template, thanks to a related discussion that took place at #1079.

This approach can have all configuration in a single file, vite.config.ts:

// @ts-expect-error – untyped module
import stylex from "@stylexjs/postcss-plugin";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";
import autoprefixer from "autoprefixer";

const babelConfig = {
  presets: ["@babel/preset-typescript"],
  plugins: [
    [
      "@stylexjs/babel-plugin",
      {
        dev: process.env.NODE_ENV === "development",
        test: process.env.NODE_ENV === "test",
        runtimeInjection: false,
        genConditionalClasses: true,
        treeshakeCompensation: true,
        unstable_moduleResolution: {
          type: "commonJS",
        },
      },
    ],
  ],
};

export default defineConfig({
  plugins: [
    react({ babel: babelConfig }),
    tsconfigPaths(),
  ],
  css: {
    postcss: {
      plugins: [
        stylex({
          babelConfig,
          include: ["./app/**/*.{js,jsx,ts,tsx}"],
          useCSSLayers: true,
        }),
        autoprefixer(),
      ],
    },
  },
});

I simplified this a bit to fit a general Vite template, and replaced @react-router/dev/vite and vite-plugin-babel with @vitejs/plugin-react, but it should work as well.

You can find a more complex example on the repo I shared earlier:
https://github.com/sergiocarneiro/example-stylex-vite-packages

And this is a repo that helped me fix my setup:
https://github.com/pawelblaszczyk5/old-rr-sandbox

[dd-jonas]

This still isn't working for me in combination with TS path aliases. Really sad and frustrating how a new library is relying on old tools like babel, instead of integrating with Vite directly.

[pawelblaszczyk5]

This still isn't working for me in combination with TS path aliases. Really sad and frustrating how a new library is relying on old tools like babel, instead of integrating with Vite directly.

This setup works flawlessly with standardized subpath imports 😉 I guess it'd also be easy to make it work with TypeScript paths but I didn't ever tried, because for a long time I migrated to using standard. In theory TypeScript paths aren't for creating non-existing aliases - they're for informing TypeScript about aliases that already exists at some tooling level 😛

[nmn]

@dd-jonas Vite is not a replacement for Babel. Only SWC is. That is a tool written in Rust and the plugins have to be written with Rust too.

Vite is a bundler that often uses Babel for transformation. The challenge here is the way Vite works in dev mode which make generating a single large CSS file very hard.

[hyperknot]

Based on @sergiocarneiro 's snippet, I made a full repo here for Vite + StyleX:

https://github.com/hyperknot/bug_repro/tree/main/vite_stylex

It works correctly, both in dev and build mode. What I cannot figure out so far is how to make it work in a pnpm workspace. I'll need some help for that.

But I think for the basic case of simple Vite + StyleX, this should be it.

[sergiocarneiro]

I have found an issue with current Vite setups, including the one I shared previously.

The issue is when using StyleX styles from published dependencies (workspace dependencies work, as Vite treats them differently). So if you install a dependency that shares styles created with StyleX, and use them in your project, you'll get the runtime error Unexpected 'stylex.create' call at runtime. Styles must be compiled by '@stylexjs/babel-plugin'.

I have created a minimal reproduction: https://github.com/sergiocarneiro/repro-stylex-vite-published-packages

[hyperknot]

Here is the stylexBabelConfig. You need to make sure the forked plugin processes your files.

const stylexBabelConfig: TransformOptions = {
  presets: ['@babel/preset-typescript'],
  plugins: [
    [
      '@stylexjs/babel-plugin',
      {
        dev: process.env.NODE_ENV === 'development',
        test: process.env.NODE_ENV === 'test',
        runtimeInjection: false,
        treeshakeCompensation: true,
        unstable_moduleResolution: {
          type: 'commonJS',
        },
        aliases: {
          '@shared/*': path.resolve('../packages/shared/*'),
        },
      },
    ],
  ],
}

[sergiocarneiro]

I tried your approach and I still can't get it to work, unfortunately. But thanks for trying!

Also, that StyleX Vite plugin you created should be the same as using vite-plugin-babel, so you may want to try that for your projects, if it works it will simplify your code:

import babel from "vite-plugin-babel";

export default defineConfig({
  plugins: [
    babel({
      babelConfig,
      loader: "jsx",
      filter: /\.[jt]sx?$/u,
    }),
  ],
  ...
});

[hyperknot]

I looked at that plugin, and it's overcomplicated in my opinion. I didn't need to touch anything related to esbuild and that plugin forces the esbuild plugin to be also used.

Also, this line really speeds up StyleX processing, running a String.includes for 'stylex'.

      // Skip files without StyleX usage for performance
      if (!filter(id) || !code.includes('stylex')) {
        return null
      }

[nmn]

The issue is when using StyleX styles from published dependencies (workspace dependencies work, as Vite treats them differently)

The implementation decisions within Vite continue to be horrifying to me.

[sergiocarneiro]

I managed to get it working by not listing the dependencies in optimizeDeps.exclude. There is still need to list them in ssr.noExternal though, which makes it work on React Router with SSR enabled. Not on Cloudflare though. There is a bug with Vite merging this property, vitejs/vite#20077, but it can be omitted when using @cloudflare/vite-plugin, since it already prevents all dependencies from being externalized using ssr.noExternal: true. Either way, it is not working, which indicates it's something else missing. Can't figure out what though.