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 delaration 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;

Webpack

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

webpack.config.js

const StylexPlugin = require('@stylexjs/webpack-plugin');
const path = require('path');

const config = (env, argv) => ({
  entry: {
    main: './src/index.js',
  },
  output: {
    path: path.resolve(__dirname, '.build'),
    filename: '[name].js',
  },
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: 'babel-loader',
      },
    ],
  },
  plugins: [
    // Ensure that the stylex plugin is used before Babel
    new StylexPlugin({
      filename: 'styles.[contenthash].css',
      // get webpack mode and set value for dev
      dev: argv.mode === 'development',
      // Use statically generated CSS files and not runtime injected CSS.
      // Even in development.
      runtimeInjection: false,
      // optional. default: 'x'
      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,
      },
    }),
  ],
  cache: true,
});

module.exports = config;

esbuild

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

build.mjs

import esbuild from 'esbuild';
import stylexPlugin from '@stylexjs/esbuild-plugin';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: './build/bundle.js',
  minify: true,
  plugins: [
    stylexPlugin({
      // If set to 'true', bundler will inject styles in-line
      // Do not use in production
      dev: false,
      // Required. File path for the generated CSS file
      generatedCSSFileName: path.resolve(__dirname, 'build/stylex.css'),
      // Aliases for StyleX package imports
      // default: '@stylexjs/stylex'
      stylexImports: ['@stylexjs/stylex'],
      // Required for CSS variable support
      unstable_moduleResolution: {
        // type: 'commonJS' | 'haste'
        // default: 'commonJS'
        type: 'commonJS',
        // The absolute path to the root of your project
        rootDir: __dirname,
      },
    }),
  ],
})

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

Local development only

Do not use in Production

You should not use @stylexjs/dev-runtime in production. It has a significant performance cost and should only be used for local development without a compiler. This runtime lacks features otherwise available when using the compiler.

To start using StyleX without having to configure a compiler and build process, you can install the local development runtime.

npm install --save-dev @stylexjs/dev-runtime

You must configure the runtime and use the returned StyleX API in the rest of your code.

import makeStyleX from '@stylexjs/dev-runtime';

export const stylex = makeStyleX({
  classNamePrefix: 'x',
  dev: true,
  test: false,
});

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"
  },
};