SWC plugin for StyleX (**unofficial)

[!WARNING] Deprecated: This package is deprecated as of version 0.3.0 and may be removed in the future. Please use the rs-compiler instead.

Overview

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

This is an unofficial plugin for StyleX. It uses SWC instead of Babel for build step, which allows us to completely ditch Babel and make StyleX faster.

This plugin successfully passes almost all tests from the official StyleX library and is designed to be a drop-in replacement for the official StyleX Babel plugin.

The usage of StyleX does not change, all changes are internal.

This plugin is particularly beneficial for Next.js projets as it allows the use of the SWC Next.js Compiler.

• Next.js plugin
• StyleX Documentation

Installation

To install the package, run the following command:

npm install --save-dev @stylexswc/swc-plugin

Usage

Modify your bundler configuration to use the StyleX SWC plugin.

[!NOTE] All awailable options the same as in the official StyleX Babel plugin and can be found on the StyleX babel plugin documentation page.

For example:

• Register SWC plugin in Next.js config:

module.exports = {
  swcMinify: true,
  experimental: {
    swcPlugins: [[
      "@stylexswc/swc-plugin",
      {
        dev: process.env.NODE_ENV === 'development',
        genConditionalClasses: true,
        treeshakeCompensation: true,
        aliases: {
          '@/*': [path.join(rootDir, '*')],
        },
        unstable_moduleResolution: {
          type: 'commonJS',
          rootDir: rootDir,
        },
      },
    ]],
  },
};

• Register SWC plugin in Webpack config:

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: [
          {
            loader: 'swc-loader',
            options: {
              jsc: {
                experimental: {
                  plugins: [
                    [
                      '@stylexswc/swc-plugin',
                      {
                        dev: process.env.NODE_ENV === 'development',
                        genConditionalClasses: true,
                        treeshakeCompensation: true,
                        aliases: {
                          '@/*': [path.join(rootDir, '*')],
                        },
                        unstable_moduleResolution: {
                          type: 'commonJS',
                          rootDir: rootDir,
                        },
                        // ... other options
                      },
                    ],
                  ],
                },
              },
            },
          },
        ],
      },
    ],
  },
};

• Regiter SWC plugin in Rsbuild config:

export default {
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [
            [
              '@swc/plugin-styled-components',
              {
                dev: process.env.NODE_ENV === 'development',
                genConditionalClasses: true,
                treeshakeCompensation: true,
                aliases: {
                  '@/*': [path.join(rootDir, '*')],
                },
                unstable_moduleResolution: {
                  type: 'commonJS',
                  rootDir: rootDir,
                },
                // ... other options
              },
            ],
          ],
        },
      },
    },
  },
};

Working with Metadata

Since SWC does not support receiving metadata after transformation, the process of extracting CSS styles is a bit tricky and is based on searching for a substring of metadata in the compiled application file and serializing it into JSON.

To extract metadate from compiled code, you need to add the following code to your build script:

let metadataStr = '[]';

const code = sourceCodeString.replace(
  /\/\/*__stylex_metadata_start__(?<metadata>.+)__stylex_metadata_end__/,
  (...args) => {
    metadataStr = args.at(-1)?.metadata.split('"__stylex_metadata_end__')[0];

    return '';
  }
);

const metadata = { stylex: [] };

try {
  metadata.stylex = JSON.parse(metadataStr);
} catch (e) {
  console.error('error parsing metadata', e);
}

Example of metadata:

[
  {
    "class_name": "x7z7khe",
    "style": {
      "rtl": null,
      "ltr": ".x7z7khe{padding:10px}"
    },
    "priority": 1000
  },
  {
    "class_name": "xrkmrrc",
    "style": {
      "rtl": null,
      "ltr": ".xrkmrrc{background-color:red}"
    },
    "priority": 3000
  }
]

Metadata can be used to extract CSS styles from the compiled code.

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:

//__stylex_metadata_start__[{"class_name":"x7z7khe","style":{"rtl":null,"ltr":".x7z7khe{padding:10px}"},"priority":1000},{"class_name":"xrkmrrc","style":{"rtl":null,"ltr":".xrkmrrc{background-color:red}"},"priority":3000}]__stylex_metadata_end__
import * as stylex from '@stylexjs/stylex';
const styleProps = {
  className: 'x7z7khe xrkmrrc',
};

[!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.

License

StyleX is MIT licensed. Stylex SWC plugin is also MIT licensed.