or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-build-plugin-icestark

TypeScript build plugin for Ice.js framework enabling easy integration with icestark micro-frontend solution

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/build-plugin-icestark@1.7.x

To install, run

npx @tessl/cli install tessl/npm-build-plugin-icestark@1.7.0

build-plugin-icestark

build-plugin-icestark is a TypeScript build plugin for the Ice.js framework that enables easy integration with icestark, a micro-frontend solution for large-scale systems. The plugin provides configuration options for both framework applications (which act as containers managing multiple sub-applications) and child applications (individual micro-frontend modules).

Package Information

Package Name: build-plugin-icestark
Package Type: npm
Language: TypeScript
Installation: npm install build-plugin-icestark

Core Imports

The plugin is used through the Ice.js build system configuration:

// ice.config.js
module.exports = {
  plugins: [
    ['build-plugin-icestark']
  ]
};

For newer Ice.js versions with @ice/app:

// ice.config.mts
import { defineConfig } from '@ice/app';
import icestark from 'build-plugin-icestark';

export default defineConfig({
  plugins: [icestark],
});

TypeScript types for icestark configuration are automatically available in app configuration after plugin installation.

Basic Usage

Framework Application

Configure your Ice.js application to act as a micro-frontend container:

// app.ts
const appConfig = {
  icestark: {
    type: 'framework',
    getApps: () => {
      return [{
        path: '/seller',
        title: '商家平台',
        url: [
          '//ice.alicdn.com/icestark/child-seller-react/index.js',
          '//ice.alicdn.com/icestark/child-seller-react/index.css',
        ],
      }];
    },
  },
};

Child Application

Configure your Ice.js application to be a micro-frontend module:

// app.ts
const appConfig = {
  icestark: {
    type: 'child',
  },
};

Architecture

build-plugin-icestark operates through several key components:

Build Plugin Function: Main plugin entry point that configures webpack and copies type definitions
Configuration Interface: TypeScript interfaces defining icestark integration options
Runtime Module: Handles application lifecycle for both framework and child applications
Webpack Configuration: Sets up aliases for icestark dependencies and layout components
Type System: Full TypeScript support with configuration interfaces and React component types

Capabilities

Plugin Configuration

Main build plugin function that configures the build system for icestark integration.

/**
 * build-plugin-icestark main plugin function
 * Configures webpack aliases and copies type definitions
 */
declare const plugin: (context: PluginContext) => Promise<void>;
export default plugin;

interface PluginContext {
  onGetWebpackConfig: (configFn: (config: any) => void) => void;
  getValue: (key: string) => any;
  applyMethod: (method: string, ...args: any[]) => void;
  context: { rootDir: string };
}

Configuration Types

Core configuration interface for icestark integration.

interface IIceStark {
  /** Application type - 'framework' for containers, 'child' for micro-frontends */
  type: 'framework' | 'child';
  /** Function to retrieve sub-application configurations (framework only) */
  getApps?: IGetApps;
  /** Router configuration options (framework only) */
  appRouter?: IAppRouter;
  /** Remove global layout when true (framework only) */
  removeRoutesLayout?: boolean;
  /** Custom AppRoute component (framework only) */
  AppRoute?: React.ComponentType;
  /** Custom Layout component (framework only) */
  Layout?: React.ComponentType;
  /** Custom app mount lifecycle handler (child only) */
  registerAppEnter?: (
    mountNode: HTMLElement,
    App: React.ComponentType,
    resolve: (value?: unknown) => void
  ) => void;
  /** Custom app unmount lifecycle handler (child only) */
  registerAppLeave?: (mountNode: HTMLElement) => void;
}

Application Discovery

Function interface for retrieving sub-application configurations in framework applications.

interface IGetApps {
  /** Returns array of application configurations, supports async */
  (): AppConfig[] | Promise<AppConfig[]>;
}

// AppConfig is imported from @ice/stark
import { AppConfig } from '@ice/stark';

The AppConfig type from @ice/stark defines individual sub-application metadata including path, title, and resource URLs.

Router Configuration

Configuration options for the application router in framework applications.

interface IAppRouter {
  /** Component to show when sub-application fails to load */
  ErrorComponent?: React.ComponentType;
  /** Component to show while sub-application is loading */
  LoadingComponent?: React.ComponentType;
  /** Component to show when route is not found */
  NotFoundComponent?: React.ComponentType;
  /** Function to determine if assets should be removed on unmount */
  shouldAssetsRemove?: (
    assetUrl?: string,
    element?: HTMLElement | HTMLLinkElement | HTMLStyleElement | HTMLScriptElement,
  ) => boolean;
}

Runtime Components

Default layout component provided by the plugin.

/**
 * Default layout wrapper component
 * @param props - Component props
 * @param props.children - React children to render
 */
declare const Layout: React.FunctionComponent<{ children: React.ReactNode }>;

Ice.js router component for handling routing within the icestark environment.

/**
 * Ice router component for icestark integration
 * @param props - Router configuration props
 */
interface IceRouterProps {
  type: string;
  routes: any[];
  basename: string;
  history: any;
  fallback?: React.ComponentType;
}

declare const IceRouter: React.FunctionComponent<IceRouterProps>;
export { IceRouter };

Utility Functions

Layout removal utility for route manipulation.

/**
 * Removes root layout from route structure
 * Used when removeRoutesLayout option is enabled
 * @param routes - Array of route objects
 * @returns Modified routes array with root layout removed
 */
declare function removeLayout(routes: any[]): any[];
export default removeLayout;

Runtime Module

Core runtime module that handles application lifecycle for both framework and child applications.

/**
 * Runtime module for icestark integration
 * Configures application behavior based on type (framework or child)
 */
declare const module: (context: RuntimeContext) => void;
export default module;

interface RuntimeContext {
  appConfig: { icestark?: IIceStark; router: RouterConfig };
  addDOMRender: (renderFn: (props: { App: React.ComponentType; appMountNode: HTMLElement }) => Promise<void>) => void;
  setRenderRouter: (routerFn: (routes: any[]) => () => React.ReactElement) => void;
  modifyRoutes: (modifyFn: (routes: any[]) => any[]) => void;
  createHistory: (options: { type: string; basename?: string }) => any;
}

interface RouterConfig {
  type: string;
  basename?: string;
  modifyRoutes?: (routes: any[]) => any[];
  fallback?: React.ComponentType;
}

Error Handling

The plugin handles common integration scenarios:

Missing Layout: Automatically falls back to built-in layout component if no custom layout exists
Build Configuration: Properly configures webpack aliases to resolve icestark dependencies
Type Safety: Provides TypeScript definitions for all configuration options

Framework applications must implement error handling in their getApps function and can provide custom error components via appRouter.ErrorComponent.

External Dependencies

This plugin integrates with the icestark ecosystem:

@ice/stark: Provides AppConfig, AppRouter, and AppRoute components for framework applications
@ice/stark-app: Provides utilities for child applications including isInIcestark(), getMountNode(), registerAppEnter(), registerAppLeave(), and getBasename()