@stylexswc/rs-compiler v0.8.1

NAPI-RS compiler for StyleX (**unofficial)

StyleX is a JavaScript library developed by Meta for defining styles optimized for user interfaces. You can find the official repository here.

!WARNING This is an unofficial style compiler for StyleX.

Overview

This package provides an unofficial, high-performance compiler for StyleX, a popular library from Meta for building optimized user interfaces. It leverages the power of NAPI-RS and SWC to achieve several key advantages:

!IMPORTANT The usage of StyleX does not change. All changes are internal.

• Faster Build Times: By utilizing SWC instead of Babel, you can potentially experience significant speed improvements during StyleX processing.
• Seamless Integration: This compiler seamlessly integrates with Next.js's default SWC Compiler, ensuring a smooth workflow.
• Drop-in Replacement: Designed to be a drop-in replacement for the official StyleX Babel plugin, minimizing disruption to existing codebases.
• Advanced Tooling Capabilities: NAPI-RS compiler unlocks access to StyleX metadata and source maps, enabling the creation of advanced plugins and tools for StyleX, ex. for creating a plugin for Webpack, Rollup, or other tools.

Advantages of a NAPI-RS compiler versus a SWC plugin

• Compability with SWC: under the hood, the NAPI-RS compiler uses SWC for parsing and transforming JavaScript code, ensuring compatibility with the latest ECMAScript features.
• Direct Access to Node.js APIs: NAPI-RS allows you to directly access Node.js APIs from your Rust code, providing greater flexibility and control.
• Improved Performance: NAPI-RS can often offer better performance than traditional Node.js addons, especially for computationally intensive tasks.
• Simplified Development: NAPI-RS simplifies the process of developing Node.js addons in Rust, making it easier to create high-performance and efficient tools.

Installation

To install the package, run the following command:

npm install --save-dev @stylexswc/rs-compiler

Transformation Process

Internally, this compiler takes your StyleX code and transforms it into a format optimized for further processing.

var { transform } = require('@stylexswc/compiler-rs');

/// ...other logic

const { code, metadata, sourcemap } = transform(
  filename,
  inputSourceCode,
  transformOptions
);

/// ...other logic

Output

The output from the compiler includes the transformed code, metadata about the generated styles, and an optional source map.

{
  "code": "import * as stylex from '@stylexjs/stylex';\nexport const styles = {\n    default: {\n        backgroundColor: \"xrkmrrc\",\n        color: \"xju2f9n\",\n        $$css: true\n    }\n};\n",
  "metadata": {
    "stylex": {
      "styles": [
        [
          "xrkmrrc",
          {
            "ltr": ".xrkmrrc{background-color:red}",
            "rtl": null
          },
          3000
        ],
        [
          "xju2f9n",
          {
            "ltr": ".xju2f9n{color:blue}",
            "rtl": null
          },
          3000
        ]
      ]
    }
  },
  "map": "{\"version\":3,\"sources\":[\"<anon>\"],\"names\":[],\"mappings\":\"AACE;AACA;;;;;;EAKG\"}"
}

Example

Below is a simple example of input StyleX code:

import * as stylex from '@stylexjs/stylex';

const styles = stylex.create({
  root: {
    padding: 10,
  },
  element: {
    backgroundColor: 'red',
  },
});

const styleProps = stylex.props(styles.root, styles.element);

Output code:

import * as stylex from '@stylexjs/stylex';
const styleProps = {
  className: 'x7z7khe xrkmrrc',
};

Compatibility

!IMPORTANT The current resolution of the exports field from package. json is only partially supported, so if you encounter problems, please open an issue with an attached link to reproduce the problem.

Debug

You can enable debug logging for the StyleX compiler using the STYLEX_DEBUG environment variable. This is useful for troubleshooting and understanding the internal processing of StyleX code.

Log Levels

The following log levels are available:

• error: Only shows error messages
• warn: Shows warnings and errors (default)
• info: Shows informational messages, warnings, and errors
• debug: Shows debug information and all above levels
• trace: Shows very detailed execution information

Usage

Set the environment variable before running your build command:

# Set to debug level
STYLEX_DEBUG=debug npm run build

# Set to trace for most verbose output
STYLEX_DEBUG=trace npm run dev

For Windows Command Prompt:

set STYLEX_DEBUG=debug && npm run build

For PowerShell:

$env:STYLEX_DEBUG="debug"; npm run build

License

StyleX is MIT licensed. StyleX NAPI-RS compiler is also MIT licensed.