@griffel/babel-preset

中文文档
1.9.2发布于 2026/09/23MITTypeScriptCommonJS近 30 天下载 9896

Babel preset with build time transforms for Griffel

原始使用文档
文档目录10 节
  1. Install
  2. Usage
  3. Importing Griffel from custom packages
  4. Configuring Babel settings
  5. Configuring module evaluation
  6. Transforms
  7. Example
  8. Access CSS output from code
  9. Troubleshooting
  10. Module evaluation

Babel preset for Griffel

A Babel preset that performs build time transforms for @griffel/react.

[!CAUTION] We don't recommend to use this preset directly, it's intended to be used by other tools like webpack loader.

Install

yarn add --dev @griffel/babel-preset
# or
npm install --save-dev @griffel/babel-preset

Usage

.babelrc

{
  "presets": ["@griffel"]
}

Importing Griffel from custom packages

import { makeStyles } from 'custom-package';
// 👇 custom import names are also supported
import { createStyles } from 'custom-package';

By default, preset handles imports from @griffel/react & @fluentui/react-components, to handle imports from custom packages settings should be tweaked:

{
  "presets": [
    [
      "@griffel",
      {
        "modules": [{ "moduleSource": "custom-package", "importName": "makeStyles" }]
      }
    ]
  ]
}

Note: "custom-package" should re-export __styles function from @griffel/react

Configuring Babel settings

If you need to specify custom Babel configuration, you can pass them to babelOptions. These options will be used by the preset when parsing and evaluating modules.

{
  "presets": [
    [
      "@griffel",
      {
        "babelOptions": {
          "plugins": ["@babel/plugin-proposal-class-static-block"],
          "presets": ["@babel/preset-typescript"]
        }
      }
    ]
  ]
}

Configuring module evaluation

{
  "presets": [
    [
      "@griffel",
      {
        "evaluationRules": []
      }
    ]
  ]
}

The set of rules that defines how the matched files will be transformed during the evaluation. EvalRule is an object with two fields:

  • test is a regular expression or a function (path: string) => boolean
  • action is an Evaluator function, "ignore" or a name of the module that exports Evaluator function as a default export

If test is omitted, the rule is applicable for all the files.

The last matched rule is used for transformation. If the last matched action for a file is "ignore" the file will be evaluated as is, so that file must not contain any js code that cannot be executed in nodejs environment (it's usually true for any lib in node_modules).

If you need to compile certain modules under /node_modules/ (which can be the case in monorepo projects), it's recommended to do it on a module by module basis for faster transforms, e.g. ignore: /node_modules[\/\\](?!some-module|other-module)/.

The default setup is:

module.exports = {
  presets: [
    [
      '@griffel',
      {
        evaluationRules: [
          {
            action: require('@griffel/babel-preset').shakerEvaluator,
          },
          {
            test: /[/\\]node_modules[/\\]/,
            action: 'ignore',
          },
        ],
      },
    ],
  ],
};

Transforms

This preset is designed to perform build time transforms for @griffel/react, it supports both ES modules and CommonJS, thus can be used in post-processing after TypeScript, for example.

Transforms applied by this preset allow stripping runtime part of makeStyles() and improve performance.

Example

Transforms

import { makeStyles } from '@griffel/react';

const useStyles = makeStyles({
  root: { color: 'red' },
});

roughly to

import { __styles } from '@griffel/react';

const useStyles = __styles(/* resolved styles */);

Access CSS output from code

It's possible to configure the preset to return all the evaluated styles of a file. This metadata looks something like below:

const output = {
  // makeStyles
  cssEntries: {
    // by each hook
    useStyles1: {
      // by each slot
      root: [".fxxxxx { color: 'red' }"],
    },
    useStyles2: {
      root: [".fxxxxx { color: 'red' }"],
    },
  },
  // makeResetStyles
  cssResetEntries: {
    // by each hook
    useResetStyles1: [".fxxxxx { color: 'red' }"],
    useResetStyles2: [".fxxxxx { color: 'red' }"],
  },
};

This is intended for programmatic transforms in code so that they can be reused by other tooling without extra steps to determine the output styles

import { griffelPreset, BabelPluginMetadata } from '@griffel/babel-preset';

const babelFileResult = Babel.transformFromAstSync(babelAST, sourceCode, {
  babelrc: false,
  configFile: false,
  presets: [[griffelPreset, { generateMetadata: true }]],

  filename: options.filename,

  sourceMaps: options.enableSourceMaps,
  sourceFileName: options.filename,
  inputSourceMap: options.inputSourceMap,
});

// metadata
console.log(babelFileResult.metadata as unknown as BabelPluginMetadata);

Troubleshooting

This section focuses mainly on troubleshooting this babel preset in the microsoft/fluentui repo. However, the concepts are not coupled to the repo setup.

Module evaluation

The preset uses tools from linaria to evaluate runtime calls of makeStyles. Linaria's debugging documentation can help here.

Debugging output can be activated with following environment variables:

$ DEBUG=linaria\* LINARIA_LOG=debug yarn build

On Windows it's required to set environment variables via set or you can use cross-env, for example:

$ cross-env DEBUG=linaria\* LINARIA_LOG=debug yarn build

The debug output will include:

  • Prepared code
  • Evaluated code
  • AST that indicates what code has been shaken with @linaria/shaker

版本与发布记录

@griffel/babel-preset 共发布 65 个版本,首次发布于 2022/01/24;过去 12 个月发布了 10 个版本。

版本发布日期距今
1.9.2latest2026/09/231 个月前
1.9.12026/07/034 个月前
1.9.02026/05/275 个月前
1.8.62026/05/215 个月前
1.8.52026/05/215 个月前
1.8.42026/05/046 个月前

关于 @griffel/babel-preset 的常见问题

@griffel/babel-preset 是什么?

Babel preset with build time transforms for Griffel

如何安装 @griffel/babel-preset?

在项目目录运行 npm install @griffel/babel-preset,或使用 pnpm add / yarn add / bun add。

@griffel/babel-preset 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@griffel/babel-preset 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@griffel/babel-preset 可以商用吗?

@griffel/babel-preset 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@griffel/babel-preset 的下载量有多少?

根据 npm 官方下载统计,@griffel/babel-preset 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,896 次,日均约 330 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@griffel/babel-preset 还在维护吗?

最新版本 1.9.2 发布于 2026/09/23(1 个月前);至今共发布 65 个版本,其中过去 12 个月发布了 10 个;首次发布于 2022/01/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。