跳到主要内容

安装

运行时​

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

npm install --save @stylexjs/stylex

编译器​

在开发和生产环境中使用 StyleX 的推荐方式是使用 构建时编译器（build-time compiler）。

开发时​

开发时，只需配置 StyleX 的 Babel 插件即可， 以便在编译时处理样式。该插件将完成样式编译以及在 JavaScript 模块中插入运行时 样式注入代码。

npm install --save-dev @stylexjs/babel-plugin
// babel.config.js
import styleXPlugin from '@stylexjs/babel-plugin';

const config = {
  plugins: [
    [
      styleXPlugin,
      {
        dev: true,
        // Set this to true for snapshot testing
        // default: false
        test: false,
        // 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;

生产环境​

在生产环境中使用 StyleX 时，需要将 CSS 提取到外部文件中。这可以 使用任何支持 Babel 的打包程序并利用 StyleX 插件生成的元数据来 完成。有关 @stylexjs/babel-plugin 插件的更多详情， 请参阅其 API 手册。

为了让 StyleX 更容易被常用的软件包和元框架（meta-frameworks）所使用，StyleX 为 Webpack、 Rollup、 Next.js 和 esbuild 提供了（试验性的）插件。

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;
Next.js
npm install --save-dev @stylexjs/nextjs-plugin @stylexjs/babel-plugin rimraf
package.json
{
  "scripts": {
    ...,
    "predev": "rimraf .next",
    "prebuild": "rimraf .next"
  }
}
.babelrc.js
module.exports = {
  presets: ["next/babel"],
  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",
          rootDir: __dirname,
        },
      },
    ],
  ],
};
next.config.mjs
/** @type {import('next').NextConfig} */
import stylexPlugin from "@stylexjs/nextjs-plugin";

const nextConfig = {};

const __dirname = new URL(".", import.meta.url).pathname;
export default stylexPlugin({
  rootDir: __dirname,
})(nextConfig);
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",
  },
};