Combining Stylus with CSS-in-JS

In modern frontend development, style management remains one of the core challenges. CSS-in-JS achieves componentized style isolation and dynamic capabilities by embedding styles directly into JavaScript code. Conversely, Stylus, a powerful CSS preprocessor, is renowned for its variable system, nesting syntax, and mixin features. Combining the two aims to leverage the runtime logic of JavaScript alongside Stylus's robust compilation characteristics to build flexible and efficient design systems. This fusion is not merely a simple tool stacking; it requires a deep understanding of both underlying mechanisms to achieve true synergy at the code level.

Core Concept Analysis: Variable Systems and Dynamic Interpolation

The core advantage of Stylus lies in its unique variable system (@var) and mixin functionality (&), making it more expressive than traditional CSS preprocessors. However, CSS-in-JS typically relies on string templates or objects to generate styles, lacking native preprocessor features. The key to successfully combining both lies in understanding how to map Stylus's static variables to JS dynamic values.

In Stylus, variable declarations use @var, while mixins are implemented via the & symbol. For example:

@var color: #3498db
@var size: 16px

.box
  background: @color
  padding: @size

In CSS-in-JS, we typically use style={{ backgroundColor: '#3498db' }}. To combine them, we need a mechanism that allows JS code to "see" Stylus variable definitions, or conversely, enables Stylus to parse style strings generated by JS.

Implementation Path: Building Bridges with PostCSS

Since Stylus itself does not directly support JavaScript objects as values, and modern build tools (such as Webpack or Vite) often treat CSS-in-JS solutions as independent modules, the most feasible technical path is to bridge them using a PostCSS plugin. PostCSS is a universal CSS preprocessor capable of intercepting CSS code and injecting JS logic.

We can write a PostCSS plugin that checks style strings for specific markers (e.g., {{jsVar}}) during the compilation phase and replaces them with Stylus variable placeholders, or vice versa. The basic approach to implementing this bridge is as follows:

  1. Define Conversion Rules: Create a mapping table to convert dynamic values in JS into syntax recognizable by Stylus.
  2. Inject Logic: Within the PostCSS plugin, traverse the CSS AST (Abstract Syntax Tree) to find nodes containing special markers.
  3. Execute Replacement: Replace found markers with actual style values or Stylus instructions.

For instance, if JS code generates background: {{themeColor}}, the PostCSS plugin can convert it to background: @var theme-color during compilation, provided that variable is defined in the build process.

Practical Example: Dynamic Theme Switching and Mixin Application

To demonstrate the effect of combining them more intuitively, we can create a simple scenario: implementing a component that supports dark mode. Assume we use styled-components to generate style strings and convert them into Stylus code via a PostCSS plugin for compilation.

At the JS layer, we define a style object based on the theme:

const theme = {
  light: { bg: '#ffffff', text: '#000000' },
  dark: { bg: '#1a1a1a', text: '#f0f0f0' }
};

const Button = ({ isDark }) => {
  const css = `
    .button {
      background: ${theme[isDark].bg};
      color: ${theme[isDark].text};
      &::after {
        content: '';
        display: block;
      }
    }
  `;
  return <div style={css}>Button</div>;
};

At this point, the PostCSS plugin intervenes, identifying dynamic strings like ${theme[isDark].bg}. It can extract these values and generate corresponding variable definitions in Stylus:

@var theme-bg-light: #ffffff
@var theme-text-dark: #000000

.button
  background: @var theme-bg-${isDark ? 'dark' : 'light'}
  color: @var theme-text-${isDark ? 'dark' : 'light'}

In this manner, Stylus's variable system is activated, and JS dynamic logic is successfully compiled into the final CSS output.

Considerations and Best Practices in the Build Process

When implementing this combination in real-world projects, build tool compatibility must be considered. Most modern frameworks default to Sass (SCSS) or native CSS, rarely using Stylus directly. Therefore, developers need to manually configure their build scripts.

First, ensure your build toolchain supports the correct loading order for PostCSS plugins. PostCSS should be positioned before Stylus processing to parse JS-generated style strings first and then convert them into Stylus syntax. Second, variable naming conventions are crucial. To avoid conflicts, it is recommended to use a prefix mechanism, such as st- or dyn-, to distinguish statically defined Stylus variables from dynamically injected JS values.

Furthermore, performance optimization cannot be overlooked. Since component rendering may trigger style string generation and PostCSS processing every time, overly complex processing logic could lead to first-paint delays. It is advisable to predefine general theme variables during the build phase and perform conditional checks only at runtime to reduce computational burden during compilation.

Summary and Outlook

The combination of Stylus and CSS-in-JS represents an exploration direction in frontend style engineering. It breaks down the barriers between traditional CSS preprocessors and JS component libraries, providing finer-grained control capabilities. Through PostCSS as an intermediary layer, we successfully introduced Stylus's variable system and mixin functionality into the dynamic style generation process.

Although this solution currently requires additional build configuration and a certain technical threshold, it offers infinite possibilities for future design systems. As the frontend ecosystem evolves, we look forward to seeing more native tools that support such fusion, allowing developers to focus more on business logic rather than tedious style concatenation work.