@griffel/vite-plugin

中文文档
1.0.1发布于 2026/09/23MITTypeScriptES Module近 30 天下载 1.6万

Vite plugin that performs CSS extraction for Griffel

原始使用文档
文档目录6 节
  1. Install
  2. Usage
  3. Options
  4. How it works
  5. Development mode
  6. Caveats

Vite plugin to perform CSS extraction in Griffel

A plugin for Vite that performs CSS extraction for @griffel/react.

Install

yarn add --dev @griffel/vite-plugin
# or
npm install --save-dev @griffel/vite-plugin

⚠️ The plugin requires Vite 8 or above and @griffel/react 1.7.7 or above.

Usage

Within your Vite configuration, add the plugin:

import { defineConfig } from 'vite';
import { griffel } from '@griffel/vite-plugin';

export default defineConfig({
  plugins: [griffel()],
});

The plugin automatically:

  • Transforms makeStyles(), makeResetStyles(), and makeStaticStyles() calls at build time
  • Extracts CSS from these calls into stylesheets handled by Vite
  • Sorts CSS rules by specificity buckets, media queries, and container queries

No extra configuration is required: CSS is handled by Vite itself, so <link> tags in production work as usual. In development the plugin does nothing and Griffel handles styles in runtime.

Options

griffel({
  // Files to process (default: /\.[cm]?[jt]sx?$/)
  include: /\.[cm]?[jt]sx?$/,
  // Files to skip, nothing is excluded by default as dependencies may also use Griffel
  exclude: undefined,

  // Compare function for sorting media queries (default: @griffel/core's defaultCompareMediaQueries)
  compareMediaQueries: myCompareFunction,

  // Compare function for sorting container queries (default: same comparator as compareMediaQueries)
  compareContainerQueries: myCompareFunction,

  // Override the resolver used to resolve imports inside evaluated modules
  resolverFactory: myResolverFactory,

  // A salt that is added to generated class names
  classNameHashSalt: '',

  // Modules that export Griffel functions (default: ["@griffel/core", "@griffel/react", "@fluentui/react-components"])
  importsToTransform: ['@griffel/react'],

  // Functions that should be treated as Griffel style calls
  functionsToTransform: ['makeStyles', 'makeResetStyles', 'makeStaticStyles'],

  // Rules that define how matched files are transformed during the evaluation
  evaluationRules: undefined,

  // Collect and log timing stats once a build is finished
  collectStats: false,

  // Collect and log dependencies that slow down evaluation (CJS modules, "export *" barrels)
  collectPerfIssues: false,
});

How it works

The plugin is a pair of Vite plugins:

  • griffel:transform runs before other transforms (enforce: 'pre') and replaces Griffel calls with their evaluated results. The extracted CSS is served from a virtual CSS module that is imported by a transformed file.
  • griffel:extract runs after the CSS assets are produced (enforce: 'post') and merges the CSS of all chunks into the assets of entrypoints, sorting & deduplicating rules on the way.

Both apply to production builds only.

Griffel relies on the order of CSS rules: rules are grouped in style buckets and can be overridden only by rules from the same or a later bucket. As Vite emits a stylesheet per chunk, the rules of a lazy loaded chunk would be applied after the rules of an application. The plugin avoids it by moving all Griffel rules into a single stylesheet, this matches the behavior of the dedicated griffel chunk in @griffel/webpack-plugin.

Development mode

The plugin applies to production builds only (apply: 'build'). A dev server has no bundling step, so there is no stylesheet to extract rules into, and Griffel handles styles in runtime there as it does without the plugin.

Caveats

  • Files that are not ES modules are skipped, Griffel calls in them will be handled by the runtime.
  • If a project has multiple entrypoints, each of them gets a copy of all extracted Griffel CSS.

版本与发布记录

@griffel/vite-plugin 共发布 19 个版本,首次发布于 2024/01/23;过去 12 个月发布了 4 个版本。

版本发布日期距今
1.0.1latest2026/09/231 个月前
1.0.02026/08/033 个月前
0.1.162026/03/068 个月前
0.1.152026/03/068 个月前
0.1.142025/11/041 年前
0.1.132025/04/221.6 年前

关于 @griffel/vite-plugin 的常见问题

@griffel/vite-plugin 是什么?

Vite plugin that performs CSS extraction for Griffel

如何安装 @griffel/vite-plugin?

在项目目录运行 npm install @griffel/vite-plugin,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:vite(^8.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@griffel/vite-plugin 支持 TypeScript 吗?

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

@griffel/vite-plugin 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@griffel/vite-plugin 可以商用吗?

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

@griffel/vite-plugin 的下载量有多少?

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

@griffel/vite-plugin 还在维护吗?

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