@ice/plugin-fusion

@ice/plugin-fusion is an ice.js plugin that enables seamless integration of Alibaba Fusion Design components within ice.js applications. It provides automatic style importing capabilities for Fusion components, theme customization through SCSS variables, and multi-theme support through configurable theme packages.

Package Information

• Package Name: @ice/plugin-fusion
• Package Type: npm
• Language: TypeScript
• Installation: npm install @ice/plugin-fusion

Core Imports

import fusion from '@ice/plugin-fusion';

Basic Usage

import { defineConfig } from '@ice/app';
import fusion from '@ice/plugin-fusion';

export default defineConfig(() => ({
  plugins: [
    fusion({
      importStyle: true,
      themePackage: '@alifd/theme-design-pro',
      theme: {
        'primary-color': '#1890ff',
        'css-prefix': 'next-'
      }
    })
  ]
}));

Architecture

@ice/plugin-fusion integrates with the ice.js build system through several key mechanisms:

• Plugin System: Uses ice.js plugin lifecycle hooks (onGetConfig, createLogger, generator)
• Style Import Integration: Leverages @ice/style-import for automatic component style loading
• Webpack Integration: Modifies SASS loader configuration to inject theme variables
• Theme Resolution: Resolves theme package files and injects SCSS variables at build time

Capabilities

Plugin Function

Creates an ice.js plugin instance configured for Fusion Design component integration.

/**
 * Creates an ice.js plugin for Fusion Design component integration
 * @param options - Configuration options for the plugin
 * @returns Plugin configuration object with name and setup function
 */
function fusion(options?: PluginOptions): {
  name: string;
  setup: (context: any) => void;
};

interface PluginOptions {
  /** Theme configuration via SCSS variables */
  theme?: Record<string, string>;
  /** Fusion component theme package name */
  themePackage?: string;
  /** Controls automatic style importing - true, false, or 'sass' */
  importStyle?: Boolean | string;
}

Usage Examples:

// Basic style importing
fusion({ importStyle: true })

// SASS style importing with theme package
fusion({
  importStyle: 'sass',
  themePackage: '@alifd/theme-design-pro'
})

// Custom theme variables
fusion({
  importStyle: 'sass',
  theme: {
    'primary-color': '#1890ff',
    'secondary-color': '#52c41a',
    'css-prefix': 'next-'
  }
})

// Combined configuration
fusion({
  importStyle: 'sass',
  themePackage: '@alifd/theme-design-pro',
  theme: {
    'primary-color': '#1890ff'
  }
})

Style Import Integration

When importStyle is enabled, the plugin automatically integrates with @ice/style-import to load Fusion component styles.

Configuration:

• importStyle: true - Loads CSS styles (style2 files)
• importStyle: 'sass' - Loads SASS styles (style files) - recommended for theme customization
• importStyle: false - Disables automatic style importing

Internal Behavior:

• Configures @ice/style-import for @alifd/next library
• Maps component names to style paths: @alifd/next/es/${componentName.toLowerCase()}/style or style2

Theme System

The plugin provides comprehensive theme customization through SCSS variables and theme packages.

Theme Packages:

• Resolves theme package files (variables.scss, icons.scss)
• Supports popular Fusion theme packages like @alifd/theme-design-pro
• Automatically injects icon styles when available

Custom Theme Variables:

• Override any Fusion Design SCSS variable via the theme option
• Common variables: primary-color, secondary-color, css-prefix
• Variables are injected as SCSS $variable: value; statements

Multi-theme Support:

• When themePackage is configured as an array, enables multi-theme capability
• Each theme package provides its own variable overrides

Webpack Integration

The plugin modifies webpack configuration to support theme customization:

SASS Loader Configuration:

• Locates and modifies sass-loader options in webpack rules
• Injects additional SCSS content before processing
• Handles additionalData merging for existing loader configurations

Content Injection Order:

1. CSS prefix configuration: $css-prefix: 'next-' !default;
2. Theme package import: @import 'themePackage/variables.scss';
3. Custom theme variables: $variable: value;
4. Original SCSS content

Cross-platform Compatibility:

• Handles Windows/Unix path differences for theme file resolution using internal formatPath function
• Converts Windows-style paths to forward slashes for webpack compatibility
• Formats paths appropriately for webpack consumption

Error Handling and Warnings

The plugin includes built-in validation and helpful warnings:

Configuration Warnings:

• Warns when themePackage is used with importStyle: true instead of 'sass'
• Alerts users that CSS-only imports won't apply SCSS variable themes

File Resolution:

• Gracefully handles missing theme package files
• Logs errors when theme variables files cannot be resolved
• Continues operation with available configuration

Example Warning:

[Plugin Fusion] WARN: themePackage is configured, please configurate importStyle as "sass", 
ohterwise, themes defined by sass variables will not take effect.

Types

interface PluginOptions {
  /** 
   * Theme configuration via SCSS variables
   * Each key-value pair becomes: $key: value;
   */
  theme?: Record<string, string>;
  
  /** 
   * Fusion component theme package name
   * Examples: '@alifd/theme-design-pro', '@alifd/theme-ice-blue'
   */
  themePackage?: string;
  
  /** 
   * Controls automatic style importing
   * - true: Import CSS styles (style2)
   * - 'sass': Import SASS styles (style) - recommended for theming
   * - false: Disable automatic importing
   */
  importStyle?: Boolean | string;
}