跳至主要内容

安装

运行时​

所有使用 StyleX 的情况都需要安装运行时包。

npm install --save @stylexjs/stylex

编译器​

在开发和生产环境中使用 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 的更多详细信息，请参阅 API 参考。

为了简化常用包和元框架的操作，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

开发运行时必须在应用程序的 JavaScript 入口点导入并配置。

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

inject({
  classNamePrefix: 'x',
  dev: true,
  test: false,
});

完成此操作后，您可以导入并使用 @stylexjs/stylex，无需任何进一步设置，直到您准备好部署到生产环境。

使用 ESLint 捕获错误​

StyleX 编译器不会验证您的样式，并且会编译许多无效样式。您应该使用 ESLint 插件在编写样式时捕获这些错误。

npm install --save-dev @stylexjs/eslint-plugin
.eslintrc.js
module.exports = {
  plugins: ["@stylexjs"],
  rules: {
    "@stylexjs/valid-styles": "error",
  },
};