安装

运行时

所有对 StyleX 的调用都需要安装运行时软件包包。

npm install --save @stylexjs/stylex

编译器

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,
      },
    }),
  ],
})

请参阅 StyleX 示例应用程序， 以了解如何使用这些插件。

仅限本地开发使用

请勿在生产环境中使用

不要在生产环境中使用 @stylexjs/dev-runtime。它的性能代价很高， 因此只能用于不使用编译器的本地开发环境。 与使用编译器相比，时该运行时缺少某些功能。

如果想要在不配置编译器和构建流程的情况下使用 StyleX， 可以安装本地开发运行时。

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

接下来你需要配置运行时并获得一个 StyleX 对象，你就可以在其余代码中通过这个返回的对象 调用 StyleX 的 API 了。

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

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

使用 ESLint 捕获错误

StyleX 编译器不会校验你的样式代码，因此会编译出许多无效的代码。 因此，在编写样式时，你应该使用 ESLint 插件来捕获 这些编码上的错误。

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