@griffel/transform

A high-performance transformation package for Griffel that unifies CSS-in-JS transformation and extraction functionality.

• Overview
• Install
• Usage
  • Basic Transformation
• API Reference
  • transformSync(sourceCode, options)
• Evaluation Plugins
  • Built-in Plugins
    • fluentTokensPlugin
  • Custom Plugins

Overview

@griffel/transform provides a unified approach to CSS-in-JS transformation and extraction for Griffel. It replaces Babel-based processing with modern OXC-based parsing for improved performance while maintaining full compatibility with existing Griffel APIs.

Install

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

Usage

Basic Transformation

import { transformSync } from '@griffel/transform';

const sourceCode = `
  import { makeStyles } from '@griffel/react';
  
  const useStyles = makeStyles({
    root: { color: 'red' }
  });
`;

const result = transformSync(sourceCode, {
  filename: 'styles.ts',
});

console.log(result.code); // Transformed code with __css calls
console.log(result.cssRulesByBucket); // Extracted CSS rules

API Reference

transformSync(sourceCode, options)

Transforms source code containing makeStyles or makeResetStyles calls.

Parameters:

• sourceCode (string): Source code to transform
• options (TransformOptions): Transformation options

Returns: TransformResult object containing:

• code: Transformed source code
• cssRulesByBucket: Extracted CSS rules organized by bucket type
• usedProcessing: Whether any transformations were applied
• usedVMForEvaluation: Whether VM evaluation was used

TransformOptions:

• filename (string): File path for error reporting and source maps
• classNameHashSalt? (string): Salt for CSS class name generation
• generateMetadata? (boolean): Include metadata in CSS rules
• modules? (string[]): Module sources to process
• babelOptions? (object): Babel configuration for complex evaluations
• evaluationRules? (array): Rules for determining evaluation strategy
• astEvaluationPlugins? (AstEvaluatorPlugin[]): Plugins for extending AST evaluation with custom node handling (default: [fluentTokensPlugin])

Evaluation Plugins

The AST evaluator supports a plugin system that allows extending static evaluation to handle additional AST node types. Plugins are tried in order when the base evaluator encounters a node type it doesn't handle (i.e., anything beyond Literal, ObjectExpression, and simple TemplateLiteral without expressions).

Built-in Plugins

fluentTokensPlugin

Handles Fluent UI design token expressions, transforming tokens.propertyName into var(--propertyName). Enabled by default — no configuration needed.

To disable it, pass an empty array:

const result = transformSync(sourceCode, {
  filename: 'styles.ts',
  astEvaluationPlugins: [],
});

This plugin handles:

• MemberExpression: tokens.colorBrandBackground → var(--colorBrandBackground)
• TemplateLiteral: `${tokens.spacingVerticalS} 0` → var(--spacingVerticalS) 0

Custom Plugins

You can create custom plugins by implementing the AstEvaluatorPlugin interface:

import { type AstEvaluatorPlugin, DEOPT } from '@griffel/transform';

const myPlugin: AstEvaluatorPlugin = {
  name: 'myPlugin',
  evaluateNode(node, context) {
    // Handle specific node types
    if (node.type === 'MemberExpression') {
      // Custom evaluation logic...
      return 'some-value';
    }

    // Return DEOPT to signal "can't handle this node" and let the next plugin try
    return DEOPT;
  },
};

const result = transformSync(sourceCode, {
  filename: 'styles.ts',
  astEvaluationPlugins: [myPlugin],
});

The context parameter provides:

• programAst: The full program AST for cross-referencing
• evaluateNode(node): Recursive evaluator callback that goes through base evaluation + all plugins