With Webpack

Install

Yarn

yarn add --dev @griffel/webpack-plugin

NPM

npm install --save-dev @griffel/webpack-plugin

Usage

Within your Webpack configuration object, you'll need to add the loader and the plugin from @griffel/webpack-plugin like so:

const { GriffelPlugin } = require('@griffel/webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|ts|tsx)$/,
        // Apply "exclude" only if your dependencies **do not use** Griffel
        // exclude: /node_modules/,
        use: {
          loader: '@griffel/webpack-plugin/loader',
        },
      },
      // "css-loader" is required to handle produced CSS assets by Griffel
      // you can use "MiniCssExtractPlugin.loader" to handle CSS insertion
      {
        test: /\.css$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
    ],
  },
  plugins: [new MiniCssExtractPlugin(), new GriffelPlugin()],
};

• mini-css-extract-plugin is not mandatory and is used as an example, you can use other tooling to inject CSS on a page

style-loader is not supported

style-loader does not produce necessary assets for the Griffel plugin to order CSS rules correctly. Using it to handle CSS insertion would result in partially broken styling in your app.

For better performance (to process less files) consider using include for @griffel/webpack-plugin/loader:

const { GriffelPlugin } = require('@griffel/webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|ts|tsx)$/,
        include: [
          path.resolve(__dirname, 'components'),
          /\/node_modules\/@fluentui\/,
          // see https://webpack.js.org/configuration/module/#condition
        ],
        use: {
          loader: '@griffel/webpack-plugin/loader',
        },
      },
    ],
  },
};

ignoreOrder option

If you use mini-css-extract-plugin, you may need to set it to false to remove warnings about conflicting order of CSS modules:

WARNING in chunk griffel [mini-css-extract-plugin]
Conflicting order. Following module has been added:
  - couldn't fulfill desired order of chunk group(s)

This will not affect the order of CSS modules in the final bundle as Griffel sorts own CSS modules anyway.

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  plugins: [
    new MiniCssExtractPlugin({
      ignoreOrder: true,
    }),
  ],
};

Usage with Rspack

@griffel/webpack-plugin is compatible with Rspack. The same plugin and loader work with Rspack's webpack-compatible API. Note that Rspack has built-in CSS support via experiments.css, so mini-css-extract-plugin is not needed:

const { GriffelPlugin } = require('@griffel/webpack-plugin');

module.exports = {
  mode: 'production',
  experiments: {
    css: true,
  },
  module: {
    rules: [
      {
        test: /\.(js|ts|tsx)$/,
        exclude: /node_modules/,
        use: [{ loader: '@griffel/webpack-plugin/loader' }],
      },
      // Required so that CSS assets produced by Griffel are handled by Rspack's native CSS support
      {
        test: /\.css$/,
        type: 'css',
      },
    ],
  },
  plugins: [new GriffelPlugin()],
};

Alternatively, CssExtractRspackPlugin can be used together with css-loader instead of experiments.css.

Rspack limitations

• optimization.splitChunks must be enabled, the plugin throws otherwise. It is enabled by default in production mode.
• The unstable_attachToEntryPoint option is supported only with Webpack and throws with Rspack.

Usage with Rsbuild

Rsbuild is built on top of Rspack, the plugin and the loader are added via tools.rspack:

import { defineConfig } from '@rsbuild/core';
import { GriffelPlugin } from '@griffel/webpack-plugin';

export default defineConfig({
  tools: {
    // 👇 required, see the caution below
    lightningcssLoader: false,
    rspack: {
      module: {
        rules: [
          {
            test: /\.(js|ts|tsx)$/,
            exclude: /node_modules/,
            use: [{ loader: '@griffel/webpack-plugin/loader' }],
          },
        ],
      },
      plugins: [new GriffelPlugin()],
    },
  },
});

Rsbuild already enables Rspack's native CSS support and optimization.splitChunks, no extra configuration is required for them.

tools.lightningcssLoader must be disabled

Griffel annotates extracted CSS with /** @griffel:css-start */ comments and relies on them to sort rules into style buckets. Rsbuild enables builtin:lightningcss-loader by default, which strips comments. Without them CSS is emitted in module order, so, for example, makeResetStyles() output ends up after makeStyles() output and overrides it.

The plugin emits a build warning when it detects this.

Disabling tools.lightningcssLoader also disables automatic vendor prefixing, use postcss with autoprefixer if you need it. CSS minification is unaffected as it runs after the rules are sorted.

Configuration

Please check the README of @griffel/webpack-plugin to check how to configure module evaluation and imports.