微前端 icestark

icestark 是飞冰团队针对大型系统提供的微前端解决方案，我们提供了独立插件 build-plugin-icestark 帮助 icejs 应用快速接入微前端解决方案。

框架应用#

通过模板快速创建一个微前端的框架应用（主应用）：

$ npm init ice icestark-framework @icedesign/stark-layout-scaffold
$ cd icestark-framework
$ npm install
$ npm start

如果不是通过模板创建，则需要按照下面的步骤进行改造：

添加插件 build-plugin-icestark#

安装插件依赖：

$ npm i --save-dev build-plugin-icestark

在 build.json 里引入插件：

{
  "plugins": {
    ["build-plugin-icestark", {
      "type": "framework",
      // 防止与微应用的 webpackJSONP 冲突
      "uniqueName": "frameworkJsonp",
    }],
    ["build-plugin-fusion", {
      "themeConfig": {
        // 防止与微应用里的基础组件 css prefix 冲突
        "css-prefix": "next-icestark-"
      }
    }],
  }
}

应用入口改造#

应用入口 src/app.tsx 中配置框架应用的一些运行时信息：

import { runApp } from 'ice'
+import { ConfigProvider } from '@alifd/next';
+import NotFound from '@/components/NotFound';
+import BasicLayout from '@/layouts/BasicLayout';
const appConfig = {
  app: {
    rootId: 'ice-container',
+    addProvider: ({ children }) => (
+      <ConfigProvider prefix="next-icestark-">{children}</ConfigProvider>
+    ),
  },
  router: {
+    type: 'browser',
  },
  icestark: {
+    Layout: BasicLayout,
+    getApps: async () => {
+      const apps = [{
+        path: '/seller',
+        title: '商家平台',
+        url: [
+          '//ice.alicdn.com/icestark/child-seller-react/index.js',
+          '//ice.alicdn.com/icestark/child-seller-react/index.css',
+        ],
+      }];
+      return apps;
+    },
+    appRouter: {
+      NotFoundComponent: NotFound,
+    },
  },
};

runApp(appConfig);

完整配置说明见运行时参数

微应用/子应用#

通过模板快速创建一个微应用：

# 创建微应用
$ npm init ice icestark-child @icedesign/stark-child-scaffold
$ cd icestark-child
$ npm install
$ npm start

如果不是通过模板创建，则需要按照下面的步骤进行改造：

添加插件 build-plugin-icestark#

安装插件依赖：

$ npm i --save-dev build-plugin-icestark

在 build.json 里引入插件：

{
  "plugins": {
    ["build-plugin-icestark", {
      "type": "child",
      "umd": true
    }]
  }
}

应用入口改造#

在应用入口 src/app.ts 中配置微应用相关的信息：

import { runApp } from 'ice'

const appConfig = {
  app: {
    rootId: 'ice-container',
  },
  router: {
+    type: 'browser',
  },
};

runApp(appConfig)

只需要这么简单，你的 SPA 应用就可以变成微应用了。

使用 Vite 模式#

icejs@2.0.0 + build-plugin-icestark@2.4.0 开始支持微应用使用 Vite 模式，构建出 ES Module 的产物格式

@ice/stark@2.6.0 开始支持加载 ES Module 格式的微应用

在微应用的 build.json 中添加配置：

{
+  "vite": true,
  "plugins": [
    ["build-plugin-icestark", {
+      "type": "child",
-      "umd": true,
    }]
  ]
}

同时框架应用中需要针对对应微应用配置 import 选项以支持 ES Module 格式的加载：

import { runApp } from 'ice';

runApp({
  app: {
    rootId: 'ice-container',
  },
  icestark: {
    Layout: BasicLayout,
    getApps: async () => {
      const apps = [{
        path: '/seller',
        title: '商家平台',
+        loadScriptMode: 'import',
        url: [],
      }];
      return apps;
    },
  },
});

插件参数#

运行时参数#

运行时参数配置在入口文件 appConfig.icestark 字段中，使用方式如下：

import { runApp } from 'ice';

const appConfig = {
  app: {
    getApps: async () => {
      return [];
    },
    appRouter: {
    },
  },
};

runApp(appConfig);

所有参数配置如下：

Layout#

类型：Component

框架应用独有字段，框架应用对应的布局组件。

getApps#

类型：Function
默认值：() => []

框架应用独有字段，用于获取微应用列表，单个微应用的完整配置字段请参考 AppConfig 。

appRouter#

框架应用独有字段，可传入 icestark 运行时的钩子函数和可选配置。主要有：

NotFoundComponent，匹配不到任何微应用路由时的状态。
LoadingComponent，加载过程中的 Loading 状态。
ErrorComponent，加载出现错误时的状态。

更多配置详见文档。

AppRoute#

框架应用独有字段，微应用渲染组件，可替换 icestark 内部实现的渲染组件，或将其封装 HoC 组件提供更多能力。非特殊场景不建议使用。

type#

废弃字段，推荐通过构建时参数配置。

类型：child | framework

构建时参数#

构建时参数配置在 build.json 中，如下使用方式：

{
  "plugins": [
    ["build-plugin-icestark", {
      "type": "child",
    }]
  ]
}

所有参数配置如下：

type#

类型：child | framework
默认值：framework

标识应用类型，框架应用或微应用。

umd#

类型：boolean
默认值：false

仅对微应用生效，是否构建为 UMD 格式的微应用。若配置 umd 参数，则 type 默认为 child。

library#

类型：string

构建为 UMD 规范微应用相关字段，标识 UMD 微应用全局导出的变量名。

uniqueName#

类型：string
默认：-

开启 splitChunk 或懒加载功能时，防止 webpack runtimes 冲突时使用。建议框架应用开启。

若使用 webpack5 构建应用，则无需启用该字段。

常见问题#

如何监听微应用切换#

icestark 通过 onRouteChange、onAppEnter 和 onAppLeave 来监听微应用间的切换，在 icejs 研发框架下可以通过在对应的 Layout 中实现相关钩子的监听。Layout 中接收 props 属性如下：

pathname：微应用路由切换信息，对应 onRouteChange
appEnter：渲染微应用的信息， onAppEnter
appLeave：卸载微应用的信息，对应 onAppLeave

在 Layout 使用相关属性时，结合对应属性是否发生变更来执行相应操作：

const BasicLayout = ({ pathname, appLeave, appEnter, children }) => {
  useEffect(() => {
    console.log(`微应用路由发生变化：${pathname}`);
  }, [pathname]);

  useEffect(() => {
    console.log(`卸载微应用：${appLeave.path}`);
  }, [appLeave]);

  useEffect(() => {
    console.log(`渲染微应用：${appEnter.path}`);
  }, [appEnter]);

  return (
    <div>
      {children}
    </div>
  );
};

动态修改微应用列表#

初始化微应用列表可以如上文介绍在应用入口 src/app.ts 中配置 getApps 属性即可，如果需要动态修改微应用列表，可以通过 Layout 接收的 updateApps 属性进行修改：

const BasicLayout = ({ updateApps, children }) => {
  useEffect(() => {
    updateApps([{
      path: '/seller',
      title: '商家平台',
      url: [
        '//ice.alicdn.com/icestark/child-seller-react/index.js',
        '//ice.alicdn.com/icestark/child-seller-react/index.css',
      ],
    }]);
  }, []);

  return (
    <div>
      {children}
    </div>
  );
}

UMD 规范微应用#

icestark 从 1.6.0 开始支持并推荐使用 UMD 规范的微应用，在微应用层面可以更少的降低跟主应用的耦合：

微应用依赖的 build-plugin-icestark 版本需要高于 2.0.0 才能支持构建出 UMD 规范的微应用
主应用依赖的 @ice/stark 版本需要高于 1.6.0 才能支持渲染 UMD 规范的微应用

微应用导出 UMD 规范的产物#

在 build.json 中配置 umd 属性即可导出标准 UMD 规范的微应用：

{
  "plugins": [
    ["build-plugin-icestark", {
      "umd": true
    }]
  ]
}

向微应用透传 props#

icestark 2.x 支持框架应用通过 props 自定义传递给微应用的参数。

// 框架应用
const appConfig = {
  ...
  icestark: {
    type: 'framework',
    Layout: BasicLayout,
    getApps: async () => {
      const apps = [{
        path: '/seller',
        title: '商家平台',
        url: [
          '//ice.alicdn.com/icestark/child-seller-react/index.js',
          '//ice.alicdn.com/icestark/child-seller-react/index.css',
        ],
+       props: {
+         name: 'micro-child'
+       }
      }];
      return apps;
    },
   ...
  },
};

runApp(appConfig);

在微应用中，可以通过页面级组件的 props 获取框架应用传递的参数。

function About(props) {
  const { frameworkProps: { name } } = props;
  return <div>{name}</div>;
}

微应用自定义生命周期函数#

插件 build-plugin-icestark 会默认为 ice.js 微应用提供生命周期函数。在一些业务场景下，需要自定义生命周期函数，则可以下面的示例进行配置：

import { runApp } from 'ice';
import { isInIcestark } from '@ice/stark-app';
import ReactDOM from 'react-dom';

// 微应用 app.tsx
const appConfig = {
  router: {
    type: 'browser',
  },
  icestark: {
    type: 'child',
  },
};

if (!isInIcestark()) {
  runApp(appConfig);
}

// 自定义 mount 生命周期函数
export function mount () {
  runApp(appConfig)
}

// 自定义 unmount 生命周期函数
export function unmount ({ container }) {
  ReactDOM.unmountComponentAtNode(container)
}

微应用 bundle 加载失败#

前端应用如果做了按需加载，按需加载的 bundle 默认是根据当前域名拼接地址，如果前端资源部署在非当前域名（比如 CDN）下，则需要通过手动配置 publicPath 来实现，可参考文档。

微应用开发时请求本地 Mock 接口#

通常情况下，代码中的接口请求地址都是写成类似 /api/xxx 的相对地址，请求时会根据当前域名进行拼接，如果微应用嵌入主应用进行开发，在域名变化后依旧想使用微应用的 Mock 接口或者代理配置，可以设置 baseURL 来请求非当前域名的接口地址。

import { runApp } from 'ice';

const appConfig = {
  ...
  request: {
    baseURL: '//127.0.0.1:4444',
  }
};

runApp(appConfig);

微应用本地开发如何调试#

单独微应用开发时只能看到自身的内容，无法关注到在主应用下的表现，这时候本地如果需要再启动一个主应用，开发起来就很繁琐。针对这种情况，我们推荐通过主应用的日常/线上环境调试本地微应用。

在主应用中注册微应用时，如果 url 里携带了类似 ?__env__=local 的 query，则将微应用的 url 转换为对应的本地服务地址，这样就可以方便调试微应用了。大体代码如下（可根据具体需求调整）：

// src/app.jsx
import React from 'react';
import { AppRouter, AppRoute } from '@ice/stark';
import urlParse from 'url-parse';
import BasicLayout from '@/layouts/BasicLayout';

const urlQuery = urlParse(location.href, true).query || {};

function getBundleUrl(name, version) {
  let jsUrl = `//g.alicdn.com/${name}/${version}/index.min.js`;
  let cssUrl = `//g.alicdn.com/${name}/${version}/index.min.css`;

  if (urlQuery.env === 'local') {
    jsUrl = `//127.0.0.1:${urlQuery.port}/build/js/index.js`;
    cssUrl = `//127.0.0.1:${urlQuery.port}/build/css/index.css`;
  }
  return [cssUrl, jsUrl];
}

const apps = [{
  title: '通用页面',
  url: getBundleUrl('seller', '0.1.0'),
  // ...
}]

应用启用 lazy 后，chunk 加载失败#

多个微应用均开启 lazy 加载页面，建议通过开启 sandbox 隔离微应用 windows 全局变量。如果无法开启 sandbox，则需要在主应用 onAppLeave 的阶段清空 webpackJsonp 配置：

const onAppLeave = (appConfig) => {
  window.webpackJsonp = [];
};

或建议通过构建时参数 uniqueName 隔离多个微应用的 webpack runtimes。

注意，若使用 webpack5 构建应用，则 webpack5 会默认使用 package.json 的 name 作为 uniqueName，因此也无需在 onAppLeave 阶段移除 window.webpackJsonp。

`Error: Invariant failed: You should not use <withRouter(Navigation) /> outside a <Router>`#

因为 jsx 嵌套层级的关系，在主应用的 Layout 里没法使用 react-router 提供的 API，比如 withRouter, Link, useParams 等，具体参考文档主应用中路由跳转。

启用 HashRouter#

官方推荐 BrowserRouter 作为微前端的路由模式。在某些情况下，你可以通过以下方式适配 HashRouter 路由模式。

修改主应用的路由模式

在 src/app.ts 中增加以下配置，将 router 修改为 hash。

import { runApp } from 'ice';

const appConfig = {
  router: {
-   type: 'browser',
+   type: 'hash',
  }
};

runApp(appConfig);

为微应用设置 hashType 为 true

import { runApp } from 'ice';

const appConfig: IAppConfig = {
  icestark: {
    type: 'framework',
    Layout: FrameworkLayout,
    getApps: async () => {
      const apps = [{
        path: '/seller',
        title: '商家平台',
        sandbox: true,
+       hashType: true,
        url: [
          '//dev.g.alicdn.com/nazha/ice-child-react/0.0.1/js/index.js',
          '//dev.g.alicdn.com/nazha/ice-child-react/0.0.1/css/index.css',
        ],
      }, {
        path: '/waiter',
        title: '小二平台',
        sandbox: true,
+       hashType: true,
        url: [
          '//ice.alicdn.com/icestark/child-waiter-vue/app.js',
          '//ice.alicdn.com/icestark/child-waiter-vue/app.css',
        ],
      }];
      return apps;
    },
  },
};

runApp(appConfig);

修改 FrameworkLayout 中的逻辑

此外，你可能需要自行修改 FrameworkLayout 中的逻辑，路由信息会通过 routeInfo 字段返回。

import * as React from 'react';
import BasicLayout from '../BasicLayout';
import UserLayout from '../UserLayout';

interface RouteInfo {
  hash: string;
  pathname: string;
  query: object;
  routeType: 'pushState' | 'replaceState',
}

const { useEffect } = React;
export default function FrameworkLayout(props: {
  children: React.ReactNode;
  appLeave: { path: string };
  appEnter: { path: string };
  routeInfo: RouteInfo;
}) {
  const { children, appLeave, appEnter, routeInfo } = props;
  // 如果是 HashRouter 模式
  const isHashRouter = true;
  const { hash = '', pathname } = routeInfo;
  const path = isHashRouter ? hash.replace('#', '') : pathname;
  const Layout = hash === '/login' ? UserLayout : BasicLayout;

  useEffect(() => {
    console.log('== app leave ==', appLeave);
    if (appLeave.path === '/angular' && window.webpackJsonp) {
      // remove webpackJsonp added by Angular app
      delete window.webpackJsonp;
    }
  }, [appLeave]);

  useEffect(() => {
    console.log('== app enter ==', appEnter);
  }, [appEnter]);

  return (
    <Layout pathname={path}>{children}</Layout>
  );
}

微应用改造

微应用的同样需要改造成 HashRouter 路由模式。

应用间跳转

应用间跳转可以通过 AppLink 和 appHistory，并设置 hashType 为 true。

import { AppLink, appHistory } from '@ice/stark-app';

// 示例1
const navItem = <AppLink to="/seller" hashType>{item.name}</AppLink>);

// 示例2
appHistory.push('/seller', true);

如何解决 Script Error 错误#

“ Script error. ” 是一个常见错误，但由于该错误不提供完整的报错信息（错误堆栈），问题排查往往无从下手。icestark 的 scriptAttributes 参数支持为加载的 <script /> 资源添加 crossorigin="anonymous" 来解决这个问题。

更多有关 icestark 的内容请访问 👉 官网

框架应用#

添加插件 build-plugin-icestark#

应用入口改造#

微应用/子应用#

添加插件 build-plugin-icestark#

应用入口改造#

使用 Vite 模式#

插件参数#

运行时参数#

Layout#

getApps#

appRouter#

AppRoute#

type#

构建时参数#

type#

umd#

library#

uniqueName#

常见问题#

如何监听微应用切换#

动态修改微应用列表#

UMD 规范微应用#

微应用导出 UMD 规范的产物#

向微应用透传 props#

微应用自定义生命周期函数#

微应用 bundle 加载失败#

微应用开发时请求本地 Mock 接口#

微应用本地开发如何调试#

应用启用 lazy 后，chunk 加载失败#

Error: Invariant failed: You should not use <withRouter(Navigation) /> outside a <Router>#

启用 HashRouter#

如何解决 Script Error 错误#

`Error: Invariant failed: You should not use <withRouter(Navigation) /> outside a <Router>`#