@fluentui/babel-make-styles

@fluentui/babel-make-styles

A Babel plugin that performs build time transforms for @fluentui/react-make-styles.

Install

yarn add @fluentui/babel-make-styles

Usage

.babelrc

{
  "plugins": ["module:@fluentui/babel-make-styles"]
}

Import makeStyles() from custom packages

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

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

{
  "plugins": [
    [
      "module:@fluentui/babel-make-styles",
      {
        "modules": [{ "moduleSource": "custom-package", "importName": "makeStyles" }]
      }
    ]
  ]
}

NOTE: "custom-package" should re-export __styles function from @fluentui/react-make-styles

Configuring Babel settings

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

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

Configuring module evaluation

{
  "plugins": [
    [
      "module:@fluentui/babel-make-styles",
      {
        "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 = {
  plugins: [
    [
      'module:@fluentui/babel-make-styles',
      {
        evaluationRules: [
          {
            action: require('@linaria/shaker').default,
          },
          {
            test: /[/\\]node_modules[/\\]/,
            action: 'ignore',
          },
        ],
      },
    ],
  ],
};

Transforms

This plugin is designed to performed build time transforms for @fluentui/react-make-styles, it supports both ES modules and CommonJS thus can be used in post processing after TypeScript, for example.

Transforms applied by this plugin allow to strip runtime part of makeStyles() and improve performance.

Example

Transforms

import { makeStyles } from '@fluentui/react-make-styles';

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

roughly to

import { __styles } from '@fluentui/react-make-styles';

const useStyles = __styles({
  root: {
    /* resolved styles */
  },
});

Troubleshooting

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

Linaria

The plugin uses tools from linaria to evaluate runtime calls of makeStyles. Linaria's debugging documentation can help here. Here are a few examples with building packages with linaria debug output.

Directly from the package

$ DEBUG=linaria\* LINARIA_LOG=debug yarn build

Using Lage from the root of the repo

$ DEBUG=linaria\* LINARIA_LOG=debug yarn lage build --to <package-name>

Using yarn workspace from the root of the repo

$ DEBUG=linaria\* LINARIA_LOG=debug yarn workspace <package-name> build

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

$ yarn cross-env DEBUG=linaria\* LINARIA_LOG=debug yarn workspace <package-name> build

The debug output will include:

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