Installation

Runtime

All uses of StyleX require the runtime package to be installed.

npm install --save @stylexjs/stylex

Compiler

The recommended way to use StyleX in development and production is with the build-time compiler. This can be done with any bundler that supports Babel, using the metadata generated by the StyleX plugin. See the API reference for more details on the @stylexjs/babel-plugin API.

To make this easier for commonly used packages and meta-frameworks, StyleX provides a PostCSS plugin. StyleX also provides (experimental) plugins for Webpack, Rollup, Next.js and esbuild.

PostCSS

PostCSS is the more versatile way to integrate StyleX into your project. Create a postcss.config.js file in your project root and add the StyleX plugin to it.

npm install --save-dev @stylexjs/postcss-plugin @stylexjs/babel-plugin

postcss.config.js

module.exports = {
  plugins: {
    '@stylexjs/postcss-plugin': {
      include: [
        './**/*.{js,jsx,ts,tsx}',
        // any other files that should be included
        // this should include NPM dependencies that use StyleX
      ],
      useCSSLayers: true,
    },
    autoprefixer: {},
  },
};

You must also configure the .babelrc file for StyleX to work as expected. Please see the Babel plugin API reference for more details.

.babelrc.js

module.exports = {
  presets: [
    ...
  ],
  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",
        },
      },
    ],
  ],
};

Finally, ensure that your app imports a global CSS file that includes the following declaration:

@stylex;

The PostCSS plugin will replace the declaration with the generated StyleX styles. Make sure that you only include this declaration once in your app.

Rollup

npm install --save-dev @stylexjs/rollup-plugin

rollup.config.js

import stylexPlugin from '@stylexjs/rollup-plugin';

const config = {
  input: './index.js',
  output: {
    file: './.build/bundle.js',
    format: 'es',
  },
  // Ensure that the stylex plugin is used before Babel
  plugins: [stylexPlugin({
    // Required. File path for the generated CSS file.
    fileName: './.build/stylex.css',
    // default: false
    dev: false,
    // prefix for all generated classNames
    classNamePrefix: 'x',
    // Required for CSS variable support
    unstable_moduleResolution: {
      // type: 'commonJS' | 'haste'
      // default: 'commonJS'
      type: 'commonJS',
      // The absolute path to the root directory of your project
      rootDir: __dirname,
    },
  })],
};

export default config;

Please refer to the StyleX examples for demonstrations on how to use each of these plugins.

Catch mistakes with ESLint

The StyleX compiler does not validate your styles and will compile many invalid styles. You should use the ESLint plugin to catch these mistakes when you author your styles.

npm install --save-dev @stylexjs/eslint-plugin

.eslintrc.js

module.exports = {
  plugins: ["@stylexjs"],
  rules: {
    "@stylexjs/valid-styles": "error",
    '@stylexjs/no-unused': "error",
    '@stylexjs/valid-shorthands': "warning",
    '@stylexjs/sort-keys': "warning"
  },
};