@griffel/transform 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log - @griffel/transform
+
+This log was last generated on Mon, 03 Nov 2025 15:42:47 GMT and should not be manually modified.
+
+<!-- Start content -->
+
+## 1.1.0
+
+Mon, 03 Nov 2025 15:42:47 GMT
+
+### Minor changes
+
+- Add initial @griffel/transform package boilerplate (copilot@github.com)
+- feat: add functionality (copilot@github.com)

package/README.md

@@ -0,0 +1,78 @@
+# @griffel/transform
+
+A high-performance transformation package for Griffel that unifies CSS-in-JS transformation and extraction functionality.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Overview](#overview)
+- [Features](#features)
+- [Install](#install)
+- [Usage](#usage)
+  - [Basic Transformation](#basic-transformation)
+- [API Reference](#api-reference)
+  - [transformSync(sourceCode, options)](#transformsyncsourcecode-options)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 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
+
+```bash
+yarn add --dev @griffel/transform
+# or
+npm install --save-dev @griffel/transform
+```
+
+## Usage
+
+### Basic Transformation
+
+```typescript
+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

package/evaluation/astEvaluator.d.mts

@@ -0,0 +1,12 @@
+import { Node } from 'oxc-parser';
+import { EvaluationResult } from './types.mjs';
+/**
+ * Simple static evaluator for object expressions with nested objects.
+ * Based on Babel's evaluation approach but simplified for our specific use case.
+ *
+ * Handles:
+ * - Objects with nested objects: { root: { color: 'red', padding: 0 } }
+ * - String literals, numeric literals, boolean literals, null
+ * - Simple property access
+ */
+export declare function astEvaluator(node: Node): EvaluationResult;

package/evaluation/batchEvaluator.d.mts

@@ -0,0 +1,11 @@
+import { StrictOptions } from '@linaria/babel-preset';
+import { StyleCall } from '../types.mjs';
+/**
+ * Batch evaluates all style calls in a file for better performance.
+ * Uses static evaluation first, then falls back to VM evaluation for complex expressions.
+ * Optimizes VM evaluation by sharing module loading and parsing overhead.
+ */
+export declare function batchEvaluator(sourceCode: string, filename: string, styleCalls: StyleCall[], babelOptions: NonNullable<StrictOptions['babelOptions']>, evaluationRules: NonNullable<StrictOptions['rules']>): {
+    usedVMForEvaluation: boolean;
+    evaluationResults: unknown[];
+};

package/evaluation/types.d.mts

@@ -0,0 +1,5 @@
+export interface EvaluationResult {
+    confident: boolean;
+    value?: unknown;
+    error?: Error;
+}

package/evaluation/vmEvaluator.d.mts

@@ -0,0 +1,3 @@
+import { StrictOptions } from '@linaria/babel-preset';
+import { EvaluationResult } from './types.mjs';
+export declare function vmEvaluator(sourceCode: string, filename: string, expressionCode: string, babelOptions: NonNullable<StrictOptions['babelOptions']>, evaluationRules: NonNullable<StrictOptions['rules']>): EvaluationResult;

package/index.d.mts

@@ -0,0 +1,4 @@
+export { default as shakerEvaluator } from '@linaria/shaker';
+export { EvalCache, Module } from '@linaria/babel-preset';
+export type { Evaluator, EvalRule } from '@linaria/babel-preset';
+export { transformSync, type TransformOptions, type TransformResult } from './transformSync.mjs';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@griffel/transform",
+  "version": "1.1.0",
+  "description": "A package that performs build time transforms for Griffel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/griffel"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "node": "./transform.js",
+      "types": "./index.d.mts"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@griffel/core": "^1.19.2",
+    "@linaria/babel-preset": "^3.0.0-beta.24",
+    "@linaria/shaker": "^3.0.0-beta.22",
+    "magic-string": "^0.30.19",
+    "oxc-parser": "^0.90.0",
+    "oxc-walker": "^0.5.2"
+  }
+}

package/transform.js

@@ -0,0 +1,428 @@
+import _shaker from "@linaria/shaker";
+import { default as default2 } from "@linaria/shaker";
+import { Module } from "@linaria/babel-preset";
+import { EvalCache, Module as Module2 } from "@linaria/babel-preset";
+import { parseSync } from "oxc-parser";
+import { walk } from "oxc-walker";
+import MagicString from "magic-string";
+import { resolveResetStyleRules, resolveStyleRulesForSlots, normalizeCSSBucketEntry } from "@griffel/core";
+class DeoptError extends Error {
+}
+function evaluateNode(node) {
+  switch (node.type) {
+    case "Literal":
+      return node.value;
+    case "ObjectExpression":
+      return evaluateObjectExpression(node);
+    case "TemplateLiteral":
+      return evaluateTemplateLiteral(node);
+    case "MemberExpression":
+      return evaluateMemberExpression(node);
+    default:
+      throw new DeoptError(`Unsupported node type: ${node.type}`);
+  }
+}
+function evaluateObjectExpression(node) {
+  const obj = {};
+  for (const prop of node.properties) {
+    if (prop.type !== "Property" || prop.kind !== "init") {
+      throw new DeoptError("Only standard properties are supported");
+    }
+    let key;
+    if (prop.computed) {
+      throw new DeoptError("Computed properties are not supported");
+    } else if (prop.key.type === "Identifier") {
+      key = prop.key.name;
+    } else if (prop.key.type === "Literal") {
+      const keyLiteral = prop.key;
+      if (typeof keyLiteral.value === "string" || typeof keyLiteral.value === "number") {
+        key = String(keyLiteral.value);
+      } else {
+        throw new DeoptError("Unsupported literal key type");
+      }
+    } else {
+      throw new DeoptError("Unsupported key type");
+    }
+    obj[key] = evaluateNode(prop.value);
+  }
+  return obj;
+}
+function evaluateTemplateLiteral(node) {
+  let result = "";
+  for (let i = 0; i < node.quasis.length; i++) {
+    result += node.quasis[i].value.cooked;
+    if (i < node.expressions.length) {
+      const expression = node.expressions[i];
+      if (expression.type === "MemberExpression" && expression.object.type === "Identifier" && expression.object.name === "tokens" && expression.property.type === "Identifier" && !expression.computed) {
+        result += `var(--${expression.property.name})`;
+      } else {
+        throw new DeoptError("Only tokens.propertyName expressions are supported in template literals");
+      }
+    }
+  }
+  return result;
+}
+function evaluateMemberExpression(node) {
+  if (node.object.type === "Identifier" && node.object.name === "tokens" && node.property.type === "Identifier" && !node.computed) {
+    return `var(--${node.property.name})`;
+  } else {
+    throw new DeoptError("Only tokens.propertyName member expressions are supported");
+  }
+}
+function astEvaluator(node) {
+  try {
+    return {
+      confident: true,
+      value: evaluateNode(node)
+    };
+  } catch {
+    return {
+      confident: false,
+      value: void 0
+    };
+  }
+}
+function isError(e) {
+  return Object.prototype.toString.call(e) === "[object Error]";
+}
+function vmEvaluator(sourceCode, filename, expressionCode, babelOptions, evaluationRules) {
+  const codeForEvaluation = `
+${sourceCode}
+
+const __mkPreval = (() => {
+  try {
+    return ([${expressionCode}]);
+  } catch (e) {
+    return e;
+  }
+})();
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { __mkPreval };
+}
+`;
+  try {
+    const options = {
+      displayName: false,
+      evaluate: true,
+      rules: evaluationRules,
+      babelOptions: {
+        ...babelOptions,
+        configFile: false,
+        babelrc: false
+      }
+    };
+    const mod = new Module(filename, options);
+    mod.evaluate(codeForEvaluation, ["__mkPreval"]);
+    const result = mod.exports.__mkPreval;
+    if (isError(result)) {
+      return { confident: false, error: result };
+    }
+    return { confident: true, value: result };
+  } catch (err) {
+    return { confident: false, error: err };
+  }
+}
+function batchEvaluator(sourceCode, filename, styleCalls, babelOptions, evaluationRules) {
+  const evaluationResults = new Array(styleCalls.length);
+  const argumentsCode = new Array(styleCalls.length).fill(null);
+  let vmEvaluationNeeded = false;
+  for (let i = 0; i < styleCalls.length; i++) {
+    const styleCall = styleCalls[i];
+    const staticResult = astEvaluator(styleCall.argumentNode);
+    if (staticResult.confident) {
+      evaluationResults[i] = staticResult.value;
+      continue;
+    }
+    vmEvaluationNeeded = true;
+    argumentsCode[i] = styleCall.argumentCode;
+  }
+  if (!vmEvaluationNeeded) {
+    return {
+      usedVMForEvaluation: false,
+      evaluationResults
+    };
+  }
+  const vmResult = vmEvaluator(sourceCode, filename, argumentsCode.join(","), babelOptions, evaluationRules);
+  if (!vmResult.confident) {
+    if (vmResult.error) {
+      throw vmResult.error;
+    } else {
+      throw new Error("Evaluation of a code fragment failed, this is a bug, please report it");
+    }
+  }
+  const vmValues = vmResult.value;
+  for (let i = 0; i < vmValues.length; i++) {
+    if (vmValues[i] === null) {
+      continue;
+    }
+    evaluationResults[i] = vmValues[i];
+  }
+  return {
+    usedVMForEvaluation: true,
+    evaluationResults
+  };
+}
+function dedupeCSSRules(cssRulesByBucket) {
+  return Object.fromEntries(
+    Object.entries(cssRulesByBucket).map(([styleBucketName, cssBucketEntries]) => {
+      if (styleBucketName === "m") {
+        return [
+          styleBucketName,
+          cssBucketEntries.filter(
+            (entryA, index, entries) => entries.findIndex((entryB) => entryA[0] === entryB[0]) === index
+          )
+        ];
+      }
+      return [styleBucketName, [...new Set(cssBucketEntries)]];
+    })
+  );
+}
+const shakerEvaluator = _shaker.default || _shaker;
+function buildCSSResetEntriesMetadata(cssResetEntries, cssRules, declaratorId) {
+  const cssRulesByBucket = Array.isArray(cssRules) ? { d: cssRules } : cssRules;
+  cssResetEntries[declaratorId] ??= [];
+  cssResetEntries[declaratorId] = Object.values(cssRulesByBucket).flatMap((bucketEntries) => {
+    return bucketEntries.map((bucketEntry) => {
+      if (Array.isArray(bucketEntry)) {
+        throw new Error(
+          `CSS rules in buckets for "makeResetStyles()" should not contain arrays, got: ${JSON.stringify(
+            bucketEntry
+          )})}`
+        );
+      }
+      return bucketEntry;
+    });
+  });
+}
+function buildCSSEntriesMetadata(cssEntries, classnamesMapping, cssRulesByBucket, declaratorId) {
+  const classesBySlot = Object.fromEntries(
+    Object.entries(classnamesMapping).map(([slot, cssClassesMap]) => {
+      const uniqueClasses = /* @__PURE__ */ new Set();
+      Object.values(cssClassesMap).forEach((cssClasses) => {
+        if (typeof cssClasses === "string") {
+          uniqueClasses.add(cssClasses);
+        } else if (Array.isArray(cssClasses)) {
+          cssClasses.forEach((cssClass) => uniqueClasses.add(cssClass));
+        }
+      });
+      return [slot, Array.from(uniqueClasses)];
+    })
+  );
+  const cssRules = Object.values(cssRulesByBucket).flatMap((cssRulesByBucket2) => {
+    return cssRulesByBucket2.map((bucketEntry) => {
+      const [cssRule] = normalizeCSSBucketEntry(bucketEntry);
+      return cssRule;
+    });
+  });
+  cssEntries[declaratorId] = Object.fromEntries(
+    Object.entries(classesBySlot).map(([slot, cssClasses]) => {
+      return [
+        slot,
+        cssClasses.map((cssClass) => {
+          return cssRules.find((rule) => rule.includes(cssClass));
+        })
+      ];
+    })
+  );
+}
+function concatCSSRulesByBucket(bucketA = {}, bucketB) {
+  Object.entries(bucketB).forEach(([cssBucketName, cssBucketEntries]) => {
+    bucketA[cssBucketName] = cssBucketEntries.concat(
+      bucketA[cssBucketName] || []
+    );
+  });
+  return bucketA;
+}
+function transformSync(sourceCode, options) {
+  const {
+    babelOptions = {},
+    filename,
+    classNameHashSalt = "",
+    generateMetadata = false,
+    modules = ["@griffel/core", "@griffel/react", "@fluentui/react-components"],
+    evaluationRules = [
+      { action: shakerEvaluator },
+      {
+        test: /[/\\]node_modules[/\\]/,
+        action: "ignore"
+      }
+    ]
+  } = options;
+  if (!filename) {
+    throw new Error('Transform error: "filename" option is required');
+  }
+  const parseResult = parseSync(filename, sourceCode);
+  parseResult.module.staticImports;
+  if (parseResult.errors.length > 0) {
+    throw new Error(`Failed to parse "${filename}": ${parseResult.errors.map((e) => e.message).join(", ")}`);
+  }
+  const magicString = new MagicString(sourceCode);
+  const programAst = parseResult.program;
+  const imports = [];
+  const styleCalls = [];
+  const cssEntries = {};
+  const cssResetEntries = {};
+  let cssRulesByBucket = {};
+  walk(programAst, {
+    enter(node, parent) {
+      if (node.type === "ImportDeclaration") {
+        const moduleSource = node.source.value;
+        if (modules.includes(moduleSource)) {
+          const specifiers = node.specifiers.reduce((acc, spec) => {
+            if (spec.type === "ImportSpecifier") {
+              const importedName = spec.imported;
+              if (importedName.type === "Identifier" && (importedName.name === "makeStyles" || importedName.name === "makeResetStyles")) {
+                acc.push({
+                  imported: importedName.name,
+                  local: spec.local.name,
+                  start: spec.start,
+                  end: spec.end
+                });
+              }
+            }
+            return acc;
+          }, []);
+          if (specifiers.length > 0) {
+            imports.push({
+              source: moduleSource,
+              specifiers,
+              start: node.start,
+              end: node.end
+            });
+          }
+        }
+      }
+      if (node.type === "CallExpression") {
+        let functionKind = null;
+        let importId;
+        if (node.callee.type === "Identifier") {
+          const calleeName = node.callee.name;
+          for (const importInfo of imports) {
+            const specifier = importInfo.specifiers.find((s) => s.local === calleeName);
+            if (specifier) {
+              if (node.arguments.length !== 1) {
+                throw new Error(`${functionKind}() function accepts only a single param`);
+              }
+              functionKind = specifier.imported;
+              importId = specifier.local;
+              break;
+            }
+          }
+        }
+        if (functionKind && importId) {
+          let declaratorId = "unknownHook";
+          let current = parent;
+          while (current) {
+            if (!current) {
+              break;
+            }
+            if (current.type === "VariableDeclarator" && current.id.type === "Identifier") {
+              declaratorId = current.id.name;
+              break;
+            }
+            if ("parent" in current) {
+              current = current.parent;
+              continue;
+            }
+            break;
+          }
+          const argument = node.arguments[0];
+          styleCalls.push({
+            declaratorId,
+            functionKind,
+            argumentStart: argument.start,
+            argumentEnd: argument.end,
+            argumentCode: sourceCode.slice(argument.start, argument.end),
+            argumentNode: argument,
+            callStart: node.start,
+            callEnd: node.end,
+            importId
+          });
+        }
+      }
+    }
+  });
+  if (imports.length === 0 || styleCalls.length === 0) {
+    return {
+      code: sourceCode,
+      usedProcessing: false,
+      usedVMForEvaluation: false
+    };
+  }
+  const { evaluationResults, usedVMForEvaluation } = batchEvaluator(
+    sourceCode,
+    filename,
+    styleCalls,
+    babelOptions,
+    evaluationRules
+  );
+  for (let i = 0; i < styleCalls.length; i++) {
+    const styleCall = styleCalls[i];
+    const evaluationResult = evaluationResults[i];
+    switch (styleCall.functionKind) {
+      case "makeStyles":
+        {
+          const stylesBySlots = evaluationResult;
+          const [classnamesMapping, cssRulesByBucketA] = resolveStyleRulesForSlots(stylesBySlots, classNameHashSalt);
+          if (generateMetadata) {
+            buildCSSEntriesMetadata(
+              cssEntries,
+              classnamesMapping,
+              dedupeCSSRules(cssRulesByBucket),
+              styleCall.declaratorId
+            );
+          }
+          magicString.overwrite(styleCall.argumentStart, styleCall.argumentEnd, `${JSON.stringify(classnamesMapping)}`);
+          cssRulesByBucket = concatCSSRulesByBucket(cssRulesByBucket, cssRulesByBucketA);
+        }
+        break;
+      case "makeResetStyles":
+        {
+          const styles = evaluationResult;
+          const [ltrClassName, rtlClassName, cssRules] = resolveResetStyleRules(styles, classNameHashSalt);
+          if (generateMetadata) {
+            buildCSSResetEntriesMetadata(cssResetEntries, cssRules, styleCall.declaratorId);
+          }
+          magicString.overwrite(
+            styleCall.argumentStart,
+            styleCall.argumentEnd,
+            `${JSON.stringify(ltrClassName)}, ${JSON.stringify(rtlClassName)}`
+          );
+          cssRulesByBucket = concatCSSRulesByBucket(
+            cssRulesByBucket,
+            Array.isArray(cssRules) ? { r: cssRules } : cssRules
+          );
+        }
+        break;
+    }
+  }
+  for (const importInfo of imports) {
+    for (const specifier of importInfo.specifiers) {
+      if (specifier.imported === "makeStyles") {
+        magicString.overwrite(specifier.start, specifier.end, "__css");
+      } else if (specifier.imported === "makeResetStyles") {
+        magicString.overwrite(specifier.start, specifier.end, "__resetCSS");
+      }
+    }
+  }
+  for (const styleCall of styleCalls) {
+    magicString.overwrite(
+      styleCall.callStart,
+      styleCall.callStart + styleCall.importId.length,
+      "__" + (styleCall.functionKind === "makeStyles" ? "css" : "resetCSS")
+    );
+  }
+  return {
+    code: magicString.toString(),
+    cssRulesByBucket,
+    usedProcessing: true,
+    usedVMForEvaluation
+  };
+}
+export {
+  EvalCache,
+  Module2 as Module,
+  default2 as shakerEvaluator,
+  transformSync
+};

package/transformSync.d.mts

@@ -0,0 +1,30 @@
+import { StrictOptions } from '@linaria/babel-preset';
+import { CSSRulesByBucket } from '@griffel/core';
+export type TransformOptions = {
+    filename: string;
+    classNameHashSalt?: string;
+    /**
+     * Returns the evaluated CSS rules in the file result metadata
+     * @default false
+     */
+    generateMetadata?: boolean;
+    /** Defines set of modules and imports handled by a transformPlugin. */
+    modules?: string[];
+    /**
+     * If you need to specify custom Babel configuration, you can pass them here. These options will be used by the
+     * transformPlugin when parsing and evaluating modules.
+     */
+    babelOptions?: Pick<StrictOptions['babelOptions'], 'plugins' | 'presets'>;
+    /** The set of rules that defines how the matched files will be transformed during the evaluation. */
+    evaluationRules?: StrictOptions['rules'];
+};
+export type TransformResult = {
+    code: string;
+    cssRulesByBucket?: CSSRulesByBucket;
+    usedProcessing: boolean;
+    usedVMForEvaluation: boolean;
+};
+/**
+ * Transforms passed source code with oxc-parser and oxc-walker instead of Babel.
+ */
+export declare function transformSync(sourceCode: string, options: TransformOptions): TransformResult;

package/types.d.mts

@@ -0,0 +1,12 @@
+import { Node } from 'oxc-parser';
+export interface StyleCall {
+    declaratorId: string;
+    functionKind: 'makeStyles' | 'makeResetStyles';
+    argumentStart: number;
+    argumentEnd: number;
+    argumentCode: string;
+    argumentNode: Node;
+    callStart: number;
+    callEnd: number;
+    importId: string;
+}

package/utils/dedupeCSSRules.d.mts

@@ -0,0 +1,6 @@
+import { CSSRulesByBucket } from '@griffel/core';
+/**
+ * Rules that are returned by `resolveStyles()` are not deduplicated.
+ * It's critical to filter out duplicates for build-time transform to avoid duplicated rules in a bundle.
+ */
+export declare function dedupeCSSRules(cssRulesByBucket: CSSRulesByBucket): CSSRulesByBucket;