fluentui-compat

FluentUI React complimentary components and utilities focused on render performance

This is a Rush monorepo containing performant utilities and components for FluentUI React.

Architecture

This repository is organized as a Rush monorepo using Rush.js for build orchestration and dependency management.

Structure

fluentui-compat/
├── packages/
│   ├── fluentui-compat/                    # Core compatibility library
│   │   ├── src/
│   │   │   ├── bundleIcon.tsx              # Optimized bundled icon component
│   │   │   ├── useAsync.ts                 # React hook for Async utilities
│   │   │   ├── useConst.ts                 # React hook for constant values
│   │   │   └── index.ts                    # Package exports
│   │   └── dist/                           # Built output
│   └── fluentui-compat-webpack-plugin/     # Webpack plugin for automatic imports
│       ├── src/
│       │   ├── index.ts                    # Main plugin implementation
│       │   └── importRewriteLoader.ts      # Babel-based import rewriter
│       └── examples/                       # Configuration examples
├── common/                                 # Rush configuration
└── rush.json                               # Rush configuration

API Documentation

Full API documentation is automatically generated and published to GitHub Pages: https://cascadiacollections.github.io/fluentui-compat/

The documentation is built using:

• API Extractor for generating API reports from TypeScript
• API Documenter for converting reports to markdown
• DocFX for generating the static documentation website

Getting Started

Prerequisites

• Node.js >=18.20.3
• Rush CLI: npm install -g @microsoft/rush

Installation

# Install Rush globally
npm install -g @microsoft/rush

# Clone the repository
git clone https://github.com/cascadiacollections/fluentui-compat.git
cd fluentui-compat

# Install dependencies
rush update

# Build all packages
rush build

DevContainer Support

This repository includes DevContainer configuration for consistent development environments. The DevContainer provides:

• Node.js 20 (LTS)
• Rush CLI pre-installed
• VS Code extensions for TypeScript, React, ESLint, and Jest
• Automatic dependency installation

Using DevContainer

1. Prerequisites: Install Docker and VS Code with the Dev Containers extension

2. Open in DevContainer:

   • Clone the repository
   • Open the folder in VS Code
   • When prompted, click "Reopen in Container" or use Command Palette > "Dev Containers: Reopen in Container"

3. Manual setup (if auto-setup fails):

   rush update
   rush build

The DevContainer will automatically run rush update after creation to install all dependencies.

Packages

This monorepo contains two main packages:

@cascadiacollections/fluentui-compat

The core compatibility library containing optimized FluentUI components and utilities:

• bundleIcon: Optimized higher-order component for creating compound icons
• useAsync: React hook that provides an Async instance with automatic cleanup
• useConst: React hook for creating constant values that don't change between renders

@cascadiacollections/fluentui-compat-webpack-plugin

A Webpack plugin that automatically rewrites imports from official FluentUI packages to use the optimized alternatives from the compatibility library:

• Webpack 4 & 5 Compatible: Works with both major Webpack versions
• Symbol-level Import Rewriting: Uses Babel to precisely rewrite only supported imports
• TypeScript Support: Full TypeScript definitions included
• Configurable Mappings: Customize which imports to rewrite

bundleIcon

An optimized higher-order component for creating compound icons that can switch between filled and regular variants. This component is memoized for optimal render performance.

Usage

import { bundleIcon } from "fluentui-compat";
import { HeartFilled, HeartRegular } from "@fluentui/react-icons";
import { useCallback, useState } from "react";

// Create a bundled icon component
const HeartIcon = bundleIcon(HeartFilled, HeartRegular);

// Use the component
function MyComponent() {
  const [isFavorited, setIsFavorited] = useState(false);

  const handleToggleFavorite = useCallback(() => {
    setIsFavorited((prev) => !prev);
  }, []);

  return (
    <HeartIcon
      filled={isFavorited}
      onClick={handleToggleFavorite}
      className="heart-icon"
    />
  );
}

API

bundleIcon(FilledIcon, RegularIcon)

Creates a memoized compound icon component.

Parameters:

• FilledIcon: FluentIcon - The filled variant of the icon
• RegularIcon: FluentIcon - The regular variant of the icon

Returns:

• A React component that accepts all standard SVG props plus:
  • filled?: boolean - Whether to render the filled variant
  • className?: string - CSS classes to apply
  • primaryFill?: string - Fill color for the icon

Features

• Performance Optimized: Uses React.memo for efficient re-renders
• Type Safe: Full TypeScript support with proper type definitions
• Flexible: Works with any FluentUI icon components
• Consistent: Applies standard icon class names for styling

useAsync

A React hook that provides an Async instance from @fluentui/utilities that is automatically cleaned up on component unmount.

useAsync Usage

import { useAsync } from "@cascadiacollections/fluentui-compat";
import { useCallback } from "react";

function MyComponent() {
  const async = useAsync();

  const handleClick = useCallback(() => {
    async.setTimeout(() => {
      console.log("Delayed action");
    }, 1000);
  }, [async]);

  return <button onClick={handleClick}>Start Timer</button>;
}

useAsync Features

• Automatic Cleanup: All async operations are automatically disposed when the component unmounts
• Development Warnings: Warns about potential race conditions in development mode
• React DevTools Integration: Provides debugging information in development
• Performance Optimized: Uses stable references to prevent unnecessary re-renders

Webpack Plugin Usage

For automatic import rewriting in your build process, use the webpack plugin:

npm install --save-dev @cascadiacollections/fluentui-compat-webpack-plugin

// webpack.config.js
const FluentUICompatPlugin = require("@cascadiacollections/fluentui-compat-webpack-plugin");

module.exports = {
  plugins: [new FluentUICompatPlugin()],
};

This will automatically rewrite imports like:

// Before
import { Async } from "@fluentui/utilities";

// After (automatically transformed)
import { useAsync } from "@cascadiacollections/fluentui-compat";

For more details, see the webpack plugin documentation.

Development

Building

# Build all packages
rush build

# Build a specific package
rush build --to fluentui-compat

Testing

# Run tests for all packages
rush test

# Run tests for a specific package
cd packages/fluentui-compat
pnpm test

# Run tests for the webpack plugin
cd packages/fluentui-compat-webpack-plugin
pnpm test

Linting

# Lint all packages
rush lint

# Lint a specific package
cd packages/fluentui-compat
pnpm run lint

# Lint the webpack plugin
cd packages/fluentui-compat-webpack-plugin
pnpm run lint

Contributing

Option 1: Using DevContainer (Recommended)

1. Open the repository in VS Code with Dev Containers extension
2. Reopen in container when prompted
3. Make your changes
4. Create change files: rush change (required for package modifications)
5. Run rush build to ensure everything builds
6. Run tests: cd packages/fluentui-compat && pnpm test
7. Submit a pull request

Option 2: Local Development

1. Install Rush CLI: npm install -g @microsoft/rush
2. Run rush update to install dependencies
3. Make your changes
4. Create change files: rush change (required for package modifications)
5. Run rush build to ensure everything builds
6. Run tests: cd packages/fluentui-compat && pnpm test
7. Submit a pull request

Note: Change files are required for all package modifications and are automatically verified by CI and git hooks. Git hooks are automatically installed when you run rush update. See MONOREPO.md for more details.

License

MIT