---
url: /guide/API/loadApp.md
---


与 `Garfish.run` 函数不同，run 方法是在执行后，当路由发生变化时会自动的匹配符合条件的应用执行渲染和销毁逻辑，`Garfish.loadApp` 提供了更加灵活的加载微前端应用模式，通过 `Garfish.loadApp` API 可以手动控制子应用的渲染预销毁

### 示例

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="framework">
  <TabItem value="React" label="React" default>

```jsx
import React from 'react';
import Garfish from 'garfish';
import { BrowserRouter, Route, Link, Switch } from 'react-router-dom';

function VueApp(basename) {
  useEffect(async () => {
    const app = await Garfish.loadApp('vue-app', {
      cache: true,
      basename,
      domGetter: '#container',
      entry: 'http://localhost:8092',
    });
    // 若已经渲染触发 show，只有首次渲染触发 mount，后面渲染都可以触发 show 提供性能
    app.mounted ? app.show() : await app.mount();
    return () => app.hide();
  });

  return <div id="container"></div>;
}

function App() {
  return (
    <BrowserRouter basename={'/'}>
      <Link to="/vue-app">VueApp</Link>
      <Switch>
        // 分配一个路由给 vue 应用
        <Route path="/vue-app" component={() => VueApp('/vue-app')}></Route>
      </Switch>
    </BrowserRouter>
  );
}
```

  </TabItem>
  <TabItem value="Vue" label="Vue">

> 提供 ReactApp 的 Vue 组件

```html
<template>
  <div>
    <div id="container"></div>
  </div>
</template>

<script>
  import Garfish from 'garfish';
  let appInstance = null;

  export default {
    name: 'App',
    async mounted() {
      appInstance = await Garfish.loadApp('react-app', {
        cache: true,
        basename: '/react-app',
        domGetter: '#container',
        entry: 'http://localhost:8093',
      });
      // 若已经渲染触发 show，只有首次渲染触发 mount，后面渲染都可以触发 show 提供性能
      appInstance.mounted ? appInstance.show() : await appInstance.mount();
    },

    destroyed() {
      appInstance.hide();
    },
  };
</script>
<style></style>
```

> 将 ReactApp 组件添加到路由中

```js
// index.js
import Vue from 'vue';
import VueRouter from 'vue-router';
import ReactApp from './component/ReactApp.vue';

const router = new VueRouter({
  mode: 'history',
  base: '/',
  routers: [{ path: '/react-app', component: ReactApp }],
});

new Vue({
  router,
  store,
  render: (h) => h(App),
}).$mount('#app');
```

  </TabItem>
</Tabs>

### 参数

<dl className="args-list">
  <dt><strong>name: string</strong></dt>
  <dd>子应用的名称，也是子应用的的唯一 id，若 name 的应用已经通过 run、setOptions 注册过，提供 name 时将直接获取应用的信息</dd>
  <dt><strong>Options: AppInfo</strong></dt>
  <dl className="args-list">
    <dt><strong>basename?: string（默认值: /）</strong></dt>
    <dd>子应用的基础路径，子应用所有的路由都在此基础上</dd>
    <dt><strong>entry: string</strong></dt>
    <dd>子应用的入口资源地址，可以为 HTML 子应用入口地址，也可以为JS 子应用入口地址</dd>
    <dt><strong>domGetter?: string | () => Element</strong></dt>
    <dd>子应用的挂载点，提供 string 类型时需要其值是 `cssSelector`，Garfish 内部会使用 `document.querySelector(domGetter)` 去选中子应用的挂载点。当提供函数时，子应用在路由驱动挂载和手动挂载时将会执行该函数并且期望返回一个 dom 元素 </dd>
    <dt><strong>cache?: boolean（默认值: true）</strong></dt>
    <dd>在调用 loadApp 时若已经加载过应用实例将返回相同的应用实例</dd>
    <dt><strong>props?: Object</strong></dt>
    <dd>传递给子应用的参数，子应用的生命周期将接受到该参数</dd>
  </dl>
</dl>

### 返回值

`AppInstance`

<dl className="args-list">
  <dt><strong>mounted: boolean</strong></dt>
  <dd>是否已经触发 mount 渲染函数</dd>
  <dt><strong>mount: Function</strong></dt>
  <dd>触发子应用的渲染流程：创建子应用的渲染容器、创建一个子应用的执行环境、执行子应用的所有代码、执行 provider 提供的子应用 render 函数</dd>
  <dt><strong>show: Function</strong></dt>
  <dd>触发子应用的显示流程：显示子应用的渲染容器、执行子应用的 render 函数（不会创建新的执行上下文）</dd>
  <dt><strong>unmount: Function</strong></dt>
  <dd>触发子应用的销毁流程：移除子应用的渲染容器、销毁子应用的执行上下文、子应用在渲染过程中产生的副作用都会被清除、执行 provider 提供的子应用 destroy 函数</dd>
  <dt><strong>hide: Function</strong></dt>
  <dd>触发子应用的隐藏流程：隐藏子应用的渲染容器、执行 provider 提供的子应用 destroy 函数</dd>
</dl>

### 不需要缓存的手动加载方案：

```js
// options 是可选的，如果不传，默认会从 Garfish.options 上深拷贝一份过来
const app = await Garfish.loadApp('appName', {
  domGetter: () => document.getElementById('id'),
});

// 渲染：编译子应用的代码 -> 创建应用容器 -> 调用 provider.render 渲染
// 注意：由于沙箱的实现，相同应用重复渲染，可能会导致内存泄漏问题
const success = await app.mount();
// 卸载：清除子应用的副作用 -> 调用 provider.destroy -> 销毁应用容器
const success = await app.unmount();
```

### 需要缓存的手动加载方案（推荐使用缓存）

```js
const cache = true;
const app = await Garfish.loadApp('appName', {
  domGetter: () => document.getElementById('id'),
});

// 渲染
if (cache && app.mounted) {
  const success = app.show();
} else {
  const success = await app.mount();
}
// 卸载
const success = app.hide();
```

### app.mount 做了哪些事情

1. 创建 `app` 容器并添加到文档流上
2. 编译子应用的代码
3. 拿到子应用的 `provider`
4. 调用 `app.options.beforeMount` 钩子
5. 调用 `provider.render`
6. 将 `app.display` 和 `app.mounted` 设置为 `true`
7. 将 `app` set 到 `Garfish.activeApps` 中
8. 调用 `app.options.afterMount` 钩子
   > 如果渲染失败，`app.mount` 会返回 `false`，否则渲染成功会返回 `true`，你可以根据返回值做对应的处理。

### app.unmount 做了哪些事件

1. 调用 `app.options.beforeUnmount` 钩子
2. 调用 `provider.destroy`
3. 清除编译的副作用
4. 将 `app` 的容器从文档流上移除
5. 将 `app.display` 和 `app.mounted` 设置为 `false`
6. 在 `Garfish.activeApps` 中移除当前的 `app` 实例
7. 调用 `app.options.afterUnmount` 钩子
   > 同上，可以根据返回值来判断是否卸载成功。

### app.show 做了哪些事件

1. 将 `app` 的容器添加到文档流上
2. 调用 `provider.render`
3. 将 `app.display` 设置为 `true`
   > 同上，可以根据返回值来判断是否渲染成功。

### app.hide 做了哪些事件

1. 调用 `provider.destroy`
2. 将 `app` 的容器从文档流上移除
3. 将 `app.display` 设置为 `false`
   > 同上，可以根据返回值来判断是否隐藏成功。

### 缓存

手动加载提供的了 `cache` 功能，以便复用 `app`，避免重复的编译代码造成的性能浪费，在 `Garfish.loadApp` 时，传入 `cache` 参数就可以。

 例如下面的代码：

```js
const app1 = await Garfish.loadApp('appName', {
  cache: true,
});

const app2 = await Garfish.loadApp('appName', {
  cache: true,
});

console.log(app1 === app2); // true
```

实际上，对于加载的 `promise` 也会是同一份，例如下面的 demo

```js
const promise1 = Garfish.loadApp('appName', {
  cache: true,
});

const promise2 = Garfish.loadApp('appName', {
  cache: true,
});

console.log(promise1 === promise2); // true

const app1 = await promise1;
const app2 = await promise2;
console.log(app1 === app2); // true
```



---
url: /guide/advance/__meta__.md
---




---
url: /guide/advance/nested.md
---


`Garfish` 目前的源码设计并没有针对嵌套场景进行非常好的兼容，因此不要在使用 Garfish 的嵌套场景，否则出现问题会导致问题难以排查。

## Garfish 为什么不容易支持嵌套场景

在正式介绍如何在嵌套场景下使用前，先简单介绍一下为什么 `Garfish` 现在并不推荐用户使用嵌套模式的原因：

- `Garfish` 导出的是实例不是构造函数，多个项目通过 `npm` 包的方式引用始终都是同一个实例（Garfish 最终并没有考虑多实例的情况），因此嵌套场景下使用的都是同一个 `Garfish` 实例，同一个实例会带来很明显的弊端，全局配置会影响其他应用的使用
- `Garfish` 路由驱动会劫持 `history` 等方法，沙箱会劫持 `dom` 的原型方法，这些劫持方法再应用销毁后进行恢复成本较高

## 嵌套场景如何使用

### 名称统一约束

由于在支持嵌套场景前，在 Garfish 中仅有两种项目类型：一种是主应用，另外一种是子应用，但是在支持嵌套场景后，他们的关系会有更多层次，因此约束一下他们之间的名称：

- 「子应用」：本身就是一个单纯的应用，本身不包含其他应用
- 「主应用」：包含其他的子应用，本身不作为子应用使用
- 「微主应用」：包含其他子应用，并且本身也作为其他主应用的子应用

### 使用约束

在 「Garfish 为什么不容易支持嵌套场景」一节中提到 `Garfish` 目前的整体设计并不太适合嵌套场景的使用，因此希望通过一些约束来减少上述的使用问题，并且将约束后可能产生的影响也同步给用户，让用户根据实际情况进行判断。

由于 `Garfish` 并未直接导出构造函数，而是通过直接导出 `Garfish` 实例，因此在实际使用中要尽可能的避免实例上全局配置带来的影响：

- 「主应用」、「微主应用」都不要使用 `Garfish.run`、`Garfish.setOptions`， 这两个 `API` 都会直接更改 `Garfish` 实例上的全局配置，可以通过 [`Garfish.loadApp`](/api/loadapp) 的方式加载子应用，这样可以保证不会对 `Garfish` 实例的全局配置产生影响
- 如果「主应用」使用了 `Garfish.run` 的注意事项
  - 将配置放到 `AppInfo` 维度，这样不会对全局所有的 `App` 实例生效，只会对实际使用的 App 生效，这样会尽可能减少全局配置
  - 在 `Garfish.run` 中配置的生命周期函数不仅会触发主应用配置的加载、渲染销毁的 `hook`，在嵌套场景中「微主应用」的加载渲染子应用也会触发，因为嵌套场景使用的是同一个 `Garfish` 实例
  - 作为「微主应用」要清楚主应用上的全局配置，例如比较关键的沙箱配置，这些配置都会直接影响「微主应用」加载子应用的行为
- 「微主应用」如何判断是由「主应用」加载的，需要主应用增加环境变量例如：`window.__GARFISH_PARENT__ = true` 等标识，这个时候「微主应用」可以根据标识决定是否独立渲染
- 「微主应用」中需要保证应用的 `name` 不会与「主应用」列表的 `name` 不会发生冲突，因此为微主应用的子应用 `name` 增加特殊前缀避免与主应用发生冲突
- 在使用 `Garfish.router`、`Garfish.channel` 等实例上的方法时，可能会受到「主应用」、「微主应用」的影响，例如：
  - [`Garfish.router.push`](/api/router#garfishrouterpush) 的 `basename` 如果在「主应用」或者「微主应用」中设置了全局的 `basename`
  - [`Garfish.channel`](/api/channel) 的实例在「主应用」或者「微主应用」都是同一个，如果使用了相同的事件名或者回调函数会互相应用
  - 在使用基础类型时都需要注意这些问题
- `Garfish` 包的升级，会同时影响、主应用和微主应用

:::info 约束总结

- 不要使用 `Garfish.run`、`Garfish.setOptions` API、避免修改 `Garfish` 全局配置
- 主应用增加环境标识，通过环境判断让微主应用能够独立运行
- 将配置信息以子应用维度存放，放置 `AppInfo` 中
- [`Garfish.loadApp`](/api/loadapp) 的方式加载、渲染微前端子应用
- 使用 `Garfish` 实例的方法时，需要注意默认配置是否收到了全局配置或其他应用的影响
- `Garfish` 包的升级，会同时影响、主应用和微主应用
  :::



---
url: /guide/quick-start/index.md
---

# 介绍

微前端是一种类似于微服务的架构，是一种由独立交付的多个前端应用组成整体的架构风格，将前端应用分解成一些更小、更简单的能够独立开发、测试、部署的应用，而在用户看来仍然是内聚的单个产品。

它主要解决了两个问题：

- 随着项目迭代应用越来越庞大，难以维护；
- 跨团队或跨部门协作开发项目导致效率低下的问题；

## Garfish 起源

Garfish 起源于 [头条号](http://mp.toutiao.com) 的实际场景，随着业务发展变成一个 Monolithic-Applications （[巨石应用](https://en.wikipedia.org/wiki/Monolithic_application)）。同时由于维护的团队人员都比较分散，工程大，导致开发调试效率低、上线困难（代码合并相互依赖），成为阻塞业务发展的一个重要因素。

于是在 2018 年衍生了 Garfish 这个微前端框架，经过大量业务方实际场景的验证和打磨，Garfish 逐渐趋于成熟。并且随着更多的业务对微前端的需求，Garfish 也在不断迭代之中，已经积累了丰富的微前端问题解决经验。

## Garfish 是什么

Garfish 是一套 [微前端](https://micro-frontends.org/) 解决方案，主要用于解决现代 web 应用在前端生态繁荣和 web 应用日益复杂化两大背景下带来的跨团队协作、技术体系多样化、web 应用日益复杂化等问题：从架构层面出发将多个独立交付的前端应用组成整体，这些前端应用能够「**独立开发**」、「**独立测试**」、「**独立部署**」，但是最终在用户看来仍然是**内聚的单个产品**。

## 框架特性

- 🌈 **丰富高效的产品特征**

  - Garfish 微前端子应用支持任意多种框架、技术体系接入
  - Garfish 微前端子应用支持「**独立开发**」、「**独立测试**」、「**独立部署**」
  - 强大的预加载能力，自动记录用户应用加载习惯增加加载权重，应用切换时间极大缩短
  - 支持依赖共享，极大程度的降低整体的包体积，减少依赖的重复加载
  - 内置数据收集，有效的感知到应用在运行期间的状态
  - 支持多实例能力，可在页面中同时运行多个子应用提升了业务的拆分力度

- 📦 **高扩展性的核心模块**

  - 通过 Loader 核心模块支持 HTML entry、JS entry 的支持，接入微前端应用简单易用
  - Router 模块提供了路由驱动、主子路由隔离，用户仅需要配置路由表应用即可完成自主的渲染和销毁，无需关心内部逻辑
  - Sandbox 模块为应用的 Runtime 提供运行时隔离能力，能有效隔离 JS、Style 对应用的副作用影响
  - Store 提供了一套简单的通信数据交换机制

- 🎯 **高度可扩展的插件机制**

  - 提供业务插件满足各种定制需求

## 设计理念

![image.png](https://p-vcloud.byteimg.com/tos-cn-i-em5hxbkur4/d456c7d2235c41daa298aba69ade435f~tplv-em5hxbkur4-noop.image?width=1126&height=454)

具体可参考 [微前端架构设计](/blog/architecture) 这篇文章中的详细介绍

## 什么时候用

如果你的团队成员多、项目类型多，并且想将其打造成「内聚的单个产品」：

- 项目的团队成员来自多个团队
- 项目内多条迭代出现需求挤兑，影响测试、发布效率
- 跨空间、跨时间维度导致团队内技术体系无法统一
- 多个前端应用需要达到「内聚的单个产品」特征
- 「内聚的单个产品」中部分内容希望达到独立开发、独立发布、独立测试、独立灰度等能力



---
url: /guide/quick-start/start.md
---

# 快速开始



本节分别从主、子 应用视角出发，介绍如何通过 [Garfish API](/api/index.md) 来将应用接入 Garfish 框架

:::tip 在线预览

:::

## 主应用

通过 Garfish API 接入主应用整体流程分为 2 步：

1. 添加 `garfish` 依赖包
2. 通过 `Garfish.run`，提供挂载点、basename、子应用列表

### 1.安装依赖

```bash npm2yarn
npm install garfish --save
```

### 2.注册子应用并启动 Garfish

```js
// index.js（主应用入口处）
import Garfish from 'garfish';
Garfish.run({
  basename: '/',
  domGetter: '#subApp',
  apps: [
    {
      name: 'react',
      activeWhen: '/react',
      entry: 'http://localhost:3000', // html入口
    },
    {
      name: 'vue',
      activeWhen: '/vue',
      entry: 'http://localhost:8080/index.js', // js入口
    },
  ],
});
```

当引入 Garfish 实例，执行实例方法 `Garfish.run` 后，`Garfish` 将会立刻启动路由劫持能力。

这时 `Garfish` 将会监听浏览器路由地址变化，当浏览器的地址发生变化时，`Garfish` 框架内部便会执行匹配逻辑，当解析到当前路径符合子应用匹配逻辑时，便会自动将应用挂载至指定的 `dom` 节点上，并在此过程中会依次触发子应用加载、渲染过程中的 [生命周期钩子函数](/guide/concept/lifecycle.md).

:::tip 注意
请确保指定的节点存在于页面中，否则可能会导致出现 `Invalid domGetter "xxx"​` 错误。在 `Garfish` 开始渲染时，无法查询到该挂载节点则会提示该错误

> 解决方案

1. 将挂载点设置为常驻挂载点，不要跟随路由变化使子应用挂载点销毁和出现
2. 保证 Garfish 在渲染时挂载点存在

:::

如果你的业务需要手动控制应用加载，可以使用 [Garfish.loadApp](/api/loadApp.md) 手动加载 APP：

```typescript
// 使用 loadApp 动态挂载应用
import Garfish from 'garfish';
const app = await Garfish.loadApp('vue-app', {
  domGetter: '#container',
  entry: 'http://localhost:3000',
  cache: true,
});

// 若已经渲染触发 show，只有首次渲染触发 mount，后面渲染都可以触发 show 提升性能
app.mounted ? app.show() : await app.mount();
```

## 子应用

通过 Garfish API 接入子应用整体流程分为 3 步：

1. 调整子应用的构建配置(目前 Garfish 仅支持 umd 格式的产物)
2. 导出子应用生命周期
3. 设置应用路由 `basename`

### 1.调整子应用的构建配置

```js
// webpack.config.js
const webpack = require('webpack');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  output: {
    // 开发环境设置 true 将会导致热更新失效
    clean: isDevelopment ? false : true,
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // webpack5 使用 chunkLoadingGlobal 代替，或不填保证 package.json name 唯一即可
    jsonpFunction: 'garfish-demo-react',
    // 保证子应用的资源路径变为绝对路径
    publicPath: 'http://localhost:8080',
  },
  plugin: [
    // 保证错误堆栈信息及 sourcemap 行列信息正确
    new webpack.BannerPlugin({
      banner: 'Micro front-end',
    }),
  ],
  devServer: {
    // 保证在开发模式下应用端口不一样
    port: '8000',
    headers: {
      // 保证子应用的资源支持跨域，在上线后需要保证子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）
      'Access-Control-Allow-Origin': '*',
    },
  },
};
```

【重要】注意：

1. libraryTarget 需要配置成 umd 规范；
2. globalObject 需要设置为 'window'，以避免由于不规范的代码格式导致的逃逸沙箱；
3. 如果你的 webpack 为 v4 版本，需要设置 jsonpFunction 并保证该值唯一（否则可能出现 webpack chunk 互相影响的可能）。若为 webpack5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同；
4. publicPath 设置为子应用资源的绝对地址，避免由于子应用的相对资源导致资源变为了主应用上的相对资源。这是因为主、子应用处于同一个文档流中，相对路径是相对于主应用而言的
5. 'Access-Control-Allow-Origin': '\*' 允许开发环境跨域，保证子应用的资源支持跨域。另外也需要保证在上线后子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）；

```js
// vite.config.js
export default defineConfig({
  base: 'http://localhost:3000/',
  server: {
    port: 3000,
    cors: true,
    origin: 'http://localhost:3000',
  },
});
```

【重要】注意：

1. base 提供资源绝对路径，避免相对路径带来的资源访问问题；
2. origin 提供资源绝对路径，避免相对路径带来的资源访问问题；
3. 需要将子应用沙箱关闭 `Garfish.run({ apps: [{ ..., sandbox: false }] })`
4. 子应用的副作用将会发生逃逸，在子应用卸载后需要将对应全局的副作用清除

### 2.导出 provider 函数

> 针对子应用需要导出生命周期函数，我们提供了桥接函数 [`@garfish/bridge-react`](/guide/bridge.md) 自动包装应用的生命周期，使用`@garfish/bridge-react` 可以降低接入成本与用户出错概率，也是 garfish 推荐的子应用接入方式。

```bash npm2yarn
// 安装 @garfish/bridge-react：
npm install @garfish/bridge-react --save
```

```jsx
import { reactBridge } from '@garfish/bridge-react';

export const provider = reactBridge({
  el: '#root',
  rootComponent: RootComponent,
  errorBoundary: () => <Error />,
});
```

```tsx
import React from 'react';
import ReactDOM from 'react-dom';
import { BrowserRouter, Switch, Route, Link } from 'react-router-dom';

export const provider = () => ({
  // render 渲染函数，必须提供
  render: ({ dom, basename }) => {
    // 和子应用独立运行时一样，将子应用渲染至对应的容器节点，根据不同的框架使用不同的渲染方式
    ReactDOM.render(
      <React.StrictMode>
        <App basename={basename} />
      </React.StrictMode>,
      // 需要注意的一点是，子应用的入口是否为 HTML 类型（即在主应用的中配置子应用的 entry 地址为子应用的 html 地址），
      // 如果为 HTML 类型，需要在 dom 的基础上选中子应用的渲染节点
      // 如果为 JS 类型，则直接将 dom 作为渲染节点即可
      dom.querySelector('#root'),
    );
  },
  // destroy 应用销毁函数，必须提供
  destroy: ({ dom, basename }) => {
    // 使用框架提供的销毁函数销毁整个应用，已达到销毁框架中可能存在得副作用，并触发应用中的一些组件销毁函数
    // 需要注意的时一定要保证对应框架得销毁函数使用正确，否则可能导致子应用未正常卸载影响其他子应用
    ReactDOM.unmountComponentAtNode(
      dom ? dom.querySelector('#root') : document.querySelector('#root'),
    );
  },
});
```

### 3. 设置应用路由 `basename`

```ts
// src/component/rootComponent
import React from "react";
import { BrowserRouter } from "react-router-dom";

const RootComponent = ({ basename }) => {
  return (
    <BrowserRouter basename={basename}>
      <Routes>
        <Route path="/" element={<App />}>
          <Route path="/home" element={<Home />} />
          <Route path="*" element={<PageNotFound />} />
        </Route>
      </Routes>
    </BrowserRouter>
  )
}
```

我们在 [接入指南](/guide/demo/demo.md) 章节详细中介绍了各框架的子应用接入 Garfish 的 demo 案例及接入过程注意事项，目前提供了：

* react (version 16, 17, 18)
* vue (version 2, 3)
* vite (version 2)
* angular (version 13)

可移步 [接入指南](/guide/demo.md) 查看详细接入步骤。

## 总结

使用 Garfish API 搭建一套微前端主子应用的主要成本来自两方面

* 主应用的搭建
  * 注册子应用的基本信息
  * 使用 Garfish 在主应用上调度管理子应用
* 子应用的改造
  * 增加对应的构建配置
  * 使用 `@garfish/bridge-react` 包提供的函数包装子应用后返回 `provider` 函数并导出
  * 子应用针对不同的框架类型，添加不同 `basename` 的设置方式
    * React 在根组件中获取 `basename` 将其传递至 `BrowserRouter` 的 `basename` 属性中
    * Vue 将 `basename` 传递至 `VueRouter` 的 `basename` 属性中



---
url: /guide/quick-start/env.md
---

# 环境变量

有时候需要使用环境变量（Environment Variables）以按需控制 `Garfish` 的行为，或者通过环境变量来区分微前端的子应用是否在微前端环境下运行，进行一些兼容性逻辑的处理，下面来看看如何使用环境变量来控制 `Garfish` 的行为。

## 环境变量列表

| 名称                 | 描述                                                       | 使用场景                                                                      |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `window.__GARFISH__` | 在引入 `garfish` 包后， `window.__GARFISH__` 为 `true`     | 主要让子应用在校验是否处于微前端环境，因此建议子应用不要单独引入 `garfish` 包 |
| `window.Garfish`     | 在引入 `garfish` 包后， `window.Garfish` 为 `Garfish` 实例 | 可以使用 `Garfish` 实例上的方法，子应用也可使用该变量                         |

<!-- | `__GARFISH_EXPORTS__` | 子应用在运行时可以获得该环境变量，需要注意的是 `__GARFISH_EXPORTS__` 是环境变量而不是存储在 `window` 上的变量，直接使用 `__GARFISH_EXPORTS__` | 可用于导出 `provider` 渲染函数，而避免收到其他库的影响                        | -->

## 使用场景

### `window.__GARFISH__`

用于子应用判断当前是否处于微前端环境中。
如：在子应用入口处。增加子应用独立运行时逻辑：

```ts
if (!window.__GARFISH__) {
  ReactDOM.render(
    <RootComponent basename="/" />,
    document.querySelector('#root'),
  );
}
```

### `window.Garfish`

使用 `Garfish` 的路由进行路由跳转

```ts
window.Garfish.router.push({ path: '/test' });
```



---
url: /guide/demo/demo.md
---

# 概述

本节我们会详细讲述不同框架下的子应用如何接入 Garfish, 提供抄得走的接入案例，以下所有 demo 均可在 [garfish demo](https://github.com/modern-js-dev/garfish/tree/main/dev) 中找到实际使用案例，目前提供的 demo 案例包含：

- react (version 16, 17, 18)
- vue (version 2, 3)
- vite (version 2)
- angular (version 13)
## demo 案例

子应用的导出提供通过 `@garfish/bridge-*` 的方式和自定义导出函数两种方式，我们将在下列 demo 案例中分别讲述。

- [react 子应用](/guide/demo/react)
- [vue 子应用](/guide/demo/vue)
- [vite 子应用](/guide/demo/vite)
- [angular 子应用](/guide/demo/angular)



---
url: /guide/demo/react.md
---

# react 子应用



本节我们将详细介绍 react 框架的应用作为子应用的接入步骤。[v16/17 demo](https://github.com/modern-js-dev/garfish/tree/main/dev/app-react-17)、[v18 demo](https://github.com/modern-js-dev/garfish/blob/main/dev/app-react-18)

## react 子应用接入步骤

### 1. bridge 依赖安装

:::tip

1. 请注意，桥接函数的安装不是必须的，你可以自定义导出函数。
2. 我们提供桥接函数是为了进一步降低用户接入成本并降低用户出错概率，桥接函数中将会内置一些默认行为，可以避免由于接入不规范导致的错误，所以这也是我们推荐的接入方式。

:::

```bash npm2yarn
npm install @garfish/bridge-react --save
```

### 2. 入口文件处导出 provider 函数

更多 bridge 函数参数介绍请参考 [这里](/guide/concept/bridge.md)

### react v16、v17 导出

```tsx
// src/index.tsx
import { reactBridge } from '@garfish/bridge-react';
import RootComponent from './components/root';
import Error from './components/ErrorBoundary';

export const provider = reactBridge({
  // 子应用挂载点，若子应用构建成 js ，则不需要传递该值
  el: '#root',
  // 根组件, bridge 会默认传递 basename、dom、props 等信息到根组件
  rootComponent: RootComponent,
  // 设置应用的 errorBoundary
  errorBoundary: () => <Error />,
});
```

```tsx
 // src/index.tsx
 import React from "react";
 import ReactDOM from "react-dom";
 import RootComponent from "./components/root";

 export const provider = () => {
   return {
     // 和子应用独立运行时一样，将子应用渲染至对应的容器节点，根据不同的框架使用不同的渲染方式
     render({ dom, basename, props}) {
       ReactDOM.render(<RootComponent {...props} />, root);
     },
     destroy({ dom, basename}) {
       // 使用框架提供的销毁函数销毁整个应用，已达到销毁框架中可能存在得副作用，并触发应用中的一些组件销毁函数
       // 需要注意的时一定要保证对应框架得销毁函数使用正确，否则可能导致子应用未正常卸载影响其他子应用
       ReactDOM.unmountComponentAtNode(
         dom ? dom.querySelector('#root') : document.querySelector('#root'),
       );
     },
   };
 };
```

### react v18 导出

```tsx
// src/index.tsx
import { reactBridge } from '@garfish/bridge-react-v18';
import RootComponent from './root';
import ErrorBoundary from './ErrorBoundary';

export const provider = reactBridge({
  el: '#root',
  rootComponent: RootComponent,
  errorBoundary: (e: any) => <ErrorBoundary />,
});

```

```tsx
// src/index.tsx
import { createRoot } from 'react-dom/client';
import RootComponent from './root';

// 在首次加载和执行时会触发该函数
export const provider = () => {
  let root = null;
  return {
    render({ basename, dom, store, props }) {
      const container = dom.querySelector('#root');
      root = createRoot(container!);
      (root as any).render(<RootComponent basename={basename} />);
    },
    destroy({ dom }) {
      (root as any).unmount();
    },
  };
};
```

### 3. 根组件设置路由的 basename

:::info

1. 为什么要设置 basename？请参考 [issue](/issues/index.md#子应用拿到-basename-的作用)
2. 我们强烈建议使用从主应用传递过来的 basename 作为子应用的 basename，而非主、子应用约定式，避免 basename 后期变更未同步带来的问题。
3. 目前主应用仅支持 history 模式的子应用路由，[why](/issues/index.md#为什么主应用仅支持-history-模式)

:::

```tsx
// src/component/rootComponent
import React from "react";
import { BrowserRouter } from "react-router-dom";

const RootComponent = ({ basename }) => {
  return (
    <BrowserRouter basename={basename}>
      <Routes>
        <Route path="/" element={<App />}>
          <Route path="/home" element={<Home />} />
          <Route path="*" element={<PageNotFound />} />
        </Route>
      </Routes>
    </BrowserRouter>
  )
}
```

### 4. 更改 webpack 配置

```js
// webpack.config.js
const webpack = require('webpack');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  output: {
    // 开发环境设置 true 将会导致热更新失效
    clean: isDevelopment ? false : true,
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // webpack5 使用 chunkLoadingGlobal 代替，或不填保证 package.json name 唯一即可
    jsonpFunction: 'garfish-demo-react',
    // 保证子应用的资源路径变为绝对路径
    publicPath: 'http://localhost:8080',
  },
  plugin: [
    // 保证错误堆栈信息及 sourcemap 行列信息正确
    new webpack.BannerPlugin({
      banner: 'Micro front-end',
    }),
  ],
  devServer: {
    // 保证在开发模式下应用端口不一样
    port: '8000',
    headers: {
      // 保证子应用的资源支持跨域，在上线后需要保证子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）
      'Access-Control-Allow-Origin': '*',
    },
  },
};
```

【重要】注意：

1. libraryTarget 需要配置成 umd 规范；
2. globalObject 需要设置为 'window'，以避免由于不规范的代码格式导致的逃逸沙箱；
3. 如果你的 webpack 为 v4 版本，需要设置 jsonpFunction 并保证该值唯一（否则可能出现 webpack chunk 互相影响的可能）。若为 webpack5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同；
4. publicPath 设置为子应用资源的绝对地址，避免由于子应用的相对资源导致资源变为了主应用上的相对资源。这是因为主、子应用处于同一个文档流中，相对路径是相对于主应用而言的
5. 'Access-Control-Allow-Origin': '\*' 允许开发环境跨域，保证子应用的资源支持跨域。另外也需要保证在上线后子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）；

### 5. 增加子应用独立运行兼容逻辑

:::tip
last but not least, 别忘了添加子应用独立运行逻辑，这能够让你的子应用脱离主应用独立运行，便于后续开发和部署。
:::

```tsx
// src/index.tsx
if (!window.__GARFISH__) {
  ReactDOM.render(
    <RootComponent
      basename={
        process.env.NODE_ENV === 'production' ? '/examples/subapp/react18' : '/'
      }
    />, document.getElementById("root"));
}
```

```tsx
// src/index.tsx
if (!window.__GARFISH__) {
  const container = document.getElementById('root');
  const root = createRoot(container!);
  root.render(
    <RootComponent
      basename={
        process.env.NODE_ENV === 'production' ? '/examples/subapp/react18' : '/'
      }
    />
  );
}
```



---
url: /guide/demo/vue.md
---

# vue 子应用

本节我们将详细介绍 vue 框架的应用作为子应用的接入步骤。[v2 demo](https://github.com/modern-js-dev/garfish/tree/main/dev/app-vue-2)、[v3 demo](https://github.com/modern-js-dev/garfish/tree/main/dev/app-vue-3)

## vue 子应用接入步骤

### 1. bridge 依赖安装

:::tip

1. 请注意，桥接函数的安装不是必须的，你可以自定义导出函数。
2. 我们提供桥接函数是为了进一步降低用户接入成本并降低用户出错概率，桥接函数中将会内置一些默认行为，可以避免由于接入不规范导致的错误，所以这也是我们推荐的接入方式。
3. 我们分别为 vue 2、3 应用提供不同的 bridge 包，目的是为了更好的类型提示及精简参数。

:::



```bash npm2yarn
npm install @garfish/bridge-vue-v2 --save
```

```bash npm2yarn
npm install @garfish/bridge-vue-v3 --save
```

### 2. 入口文件处导出 provider 函数

更多 bridge 函数参数介绍请参考 [这里](/guide/concept/bridge.md)

### vue2 导出

```js
import Vue from 'vue';
import VueRouter from 'vue-router';
import store from './store';
import App from './App.vue';
import Home from './components/Home.vue';
import { vueBridge } from '@garfish/bridge-vue-v2';

Vue.use(VueRouter);
Vue.config.productionTip = false;

function newRouter(basename) {
  const router = new VueRouter({
    mode: 'history',
    base: basename,
    routes: [
      { path: '/home', component: Home },
    ],
  });
  return router;
}

export const provider = vueBridge({
  // 根组件
  rootComponent: App,
  // 可选，注册 vue-router或状态管理对象
  appOptions: ({ basename, dom, appName, props, appInfo }) => {
  // pass the options to Vue Constructor. check https://vuejs.bootcss.com/api/#%E9%80%89%E9%A1%B9-%E6%95%B0%E6%8D%AE
    return {
      el: '#app',
      router: newRouter(basename),
      store,
    };
  },
});
```

```js
  import Vue from 'vue';
  import App from './App.vue';
  import store from './store';
  import VueRouter from 'vue-router';
  import HelloWorld from './components/HelloWorld.vue';

  Vue.use(VueRouter);
  Vue.config.productionTip = false;

  const render = ({ dom, basename = '/' }) => {
    const router = new VueRouter({
      mode: 'history',
      base: basename,
      router,
      routes: [
        { path: '/', component: HelloWorld },
      ],
    });

    const vm = new Vue({
      store,
      render: (h) => h(App, { props: { basename } }),
    }).$mount();
    (dom || document).querySelector('#app').appendChild(vm.$el);
  };
```

### vue3 导出

```js
  import { h, createApp } from 'vue';
  import { createRouter, createWebHistory } from 'vue-router';
  import { stateSymbol, createState } from './store.js';
  import App from './App.vue';
  import Home from './components/Home.vue';
  import { vueBridge } from '@garfish/bridge-vue-v3';

  const routes = [
    { path: '/home', component: Home },
  ];

  function newRouter(basename) {
    const router = createRouter({
      history: createWebHistory(basename),
      routes,
    });
    return router;
  }

  export const provider = vueBridge({
    rootComponent: App,
    // 可选，注册 vue-router或状态管理对象
    handleInstance: (vueInstance, { basename, dom, appName, props, appInfo}) => {
      vueInstance.use(newRouter(basename));
      vueInstance.provide(stateSymbol, createState());
    },
  });
```

```js
  import { h, createApp } from 'vue';
  import { createRouter, createWebHistory } from 'vue-router';
  import { stateSymbol, createState } from './store.js';
  import App from './App.vue';
  import HelloGarfish from './components/HelloGarfish.vue';

  export function provider({ dom, basename }) {
    let app = null;
    return {
      render() {
        app = createApp(App);
        app.provide(stateSymbol, createState());
        const router = createRouter({
          history: createWebHistory(basename),
          base: basename,
          routes: [{ path: '/home', component: HelloGarfish }]
        });
        app.use(router);
        app.mount(
          dom ? dom.querySelector('#app') : document.querySelector('#app'),
        );
      },
      destroy() {
        if (app) {
          app.unmount(
            dom ? dom.querySelector('#app') : document.querySelector('#app'),
          );
        }
      },
    };
  }
```

### 3. 根组件设置路由的 basename

:::tip

1. 为什么要设置 basename？请参考 [issue](/issues/index.md#子应用拿到-basename-的作用)
2. 我们强烈建议使用从主应用传递过来的 basename 作为子应用的 basename，而非主、子应用约定式，避免 basename 后期变更未同步带来的问题。
3. 目前主应用仅支持 history 模式的子应用路由，[why](/issues/index.md#为什么主应用仅支持-history-模式)

:::

```js
import Vue from 'vue';
import VueRouter from 'vue-router';
import store from './store';
import App from './App.vue';
import Home from './components/Home.vue';
import { vueBridge } from '@garfish/bridge-vue-v2';

Vue.use(VueRouter);
Vue.config.productionTip = false;

function newRouter(basename) {
  const router = new VueRouter({
    mode: 'history',
    base: basename,
    routes: [
      { path: '/home', component: Home },
    ],
  });
  return router;
}
```

```js
import { h, createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { stateSymbol, createState } from './store.js';
import App from './App.vue';
import Home from './components/Home.vue';
import { vueBridge } from '@garfish/bridge-vue-v3';

const routes = [
  { path: '/home', component: Home },
];

function newRouter(basename) {
  const router = createRouter({
    history: createWebHistory(basename),
    base: basename,
    routes,
  });
  return router;
}
```

### 4. 更改 webpack 配置

```js
// webpack.config.js
const webpack = require('webpack');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  output: {
    // 开发环境设置 true 将会导致热更新失效
    clean: isDevelopment ? false : true,
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // webpack5 使用 chunkLoadingGlobal 代替，或不填保证 package.json name 唯一即可
    jsonpFunction: 'garfish-demo-react',
    // 保证子应用的资源路径变为绝对路径
    publicPath: 'http://localhost:8080',
  },
  plugin: [
    // 保证错误堆栈信息及 sourcemap 行列信息正确
    new webpack.BannerPlugin({
      banner: 'Micro front-end',
    }),
  ],
  devServer: {
    // 保证在开发模式下应用端口不一样
    port: '8000',
    headers: {
      // 保证子应用的资源支持跨域，在上线后需要保证子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）
      'Access-Control-Allow-Origin': '*',
    },
  },
};
```

【重要】注意：

1. libraryTarget 需要配置成 umd 规范；
2. globalObject 需要设置为 'window'，以避免由于不规范的代码格式导致的逃逸沙箱；
3. 如果你的 webpack 为 v4 版本，需要设置 jsonpFunction 并保证该值唯一（否则可能出现 webpack chunk 互相影响的可能）。若为 webpack5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同；
4. publicPath 设置为子应用资源的绝对地址，避免由于子应用的相对资源导致资源变为了主应用上的相对资源。这是因为主、子应用处于同一个文档流中，相对路径是相对于主应用而言的
5. 'Access-Control-Allow-Origin': '\*' 允许开发环境跨域，保证子应用的资源支持跨域。另外也需要保证在上线后子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）；

### 5. 增加子应用独立运行兼容逻辑

:::tip
last but not least, 别忘了添加子应用独立运行逻辑，这能够让你的子应用脱离主应用独立运行，便于后续开发和部署。

:::

```js
// src/main.js
import Vue from 'vue';
import VueRouter from 'vue-router';

// 这能够让子应用独立运行起来，以保证后续子应用能脱离主应用独立运行，方便调试、开发
if (!window.__GARFISH__) {
    const router = new VueRouter({
      mode: 'history',
      base: '/',
      routes: [
        { path: '/home', component: Home },
      ],
    });
    new Vue({
      store,
      router,
      render: (h) => h(App),
    }).$mount('#app');
}
```

```js
// src/main.js
import { h, createApp } from 'vue';
import VueRouter from 'vue-router';

// 这能够让子应用独立运行起来，以保证后续子应用能脱离主应用独立运行，方便调试、开发
if (!window.__GARFISH__) {
  const router = new VueRouter({
    mode: 'history',
    base: '/',
    routes: [
      { path: '/home', component: Home },
    ],
  });
  const app = createApp(App);
  app.provide(stateSymbol, createState());
  app.use(router);
  app.mount('#app');
}
```



---
url: /guide/demo/vite.md
---

# vite 子应用

本节我们将详细介绍 vite 框架的应用作为子应用的接入步骤。[demo](https://github.com/modern-js-dev/garfish/tree/main/dev/app-vue-vite)

### 子应用沙箱状态

当 vite 应用作为子应用接入 garfish 时，我们要求子应用沙箱需关闭，否则应用将不能正常运行。

:::info 请注意：

1. 子应用沙箱默认为开启状态，请[设置子应用沙箱关闭](/guide/demo/vite.md#设置子应用沙箱关闭)；
2. 在关闭沙箱的场景下，子应用的副作用将会发生逃逸，请确保子应用卸载后对应全局的副作用被清除；

:::

### 设置子应用沙箱关闭

```js
// 主应用工程中，Garfish.run 处设置：
Garfish.run({
  ...,
  apps: [
    {
      name: 'sub-app',
      activeWhen: '/vite',
      sandbox: false
    }
  ]
})
```

:::danger
注意，不要设置 Garfish.run() 顶层的 sandbox 属性，这会导致所有子应用的沙箱关闭。

:::

## vite 子应用接入步骤

### 1. bridge 依赖安装

:::tip

1. 请注意，桥接函数的安装不是必须的，你可以自定义导出函数。
2. 我们提供桥接函数是为了进一步降低用户接入成本并降低用户出错概率，桥接函数中将会内置一些默认行为，可以可以避免由于接入不规范导致的错误，所以这也是我们推荐的接入方式。

:::

```bash npm2yarn
npm install @garfish/bridge-vue-v3 --save
```

### 2. 入口文件处导出 provider 函数

更多 bridge 函数参数介绍请参考 [这里](/guide/concept/bridge.md)

```js
// src/main.js
import { h } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { vueBridge } from '@garfish/bridge-vue-v3';
import App from './App.vue';

function newRouter(basename) {
  const router = createRouter({
    history: createWebHistory(basename),
    base: basename,
    routes,
  });
  return router;
}

export const provider = vueBridge({
  rootComponent: App,
  // 可选，注册 vue-router或状态管理对象
  appOptions: ({ basename, dom, appName, props }) => ({
    el: '#app',
    render: () => h(App),
    router: newRouter(basename),
  }),
});
```

### 3. 根组件设置路由的 basename

:::info

1. 为什么要设置 basename？请参考 [issue](/issues/index.md#子应用拿到-basename-的作用)
2. 我们强烈建议使用从主应用传递过来的 basename 作为子应用的 basename，而非主、子应用约定式，避免 basename 后期变更未同步带来的问题。
3. 目前主应用仅支持 history 模式的子应用路由，[why](/issues/index.md#为什么主应用仅支持-history-模式)

:::

```js
// src/main.js
import { h } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { vueBridge } from '@garfish/bridge-vue-v3';
import App from './App.vue';

function newRouter(basename) {
  const router = createRouter({
    history: createWebHistory(basename),
    base: basename,
    routes,
  });
  return router;
}
```

### 4. 更改 vite 配置

```js
// vite.config.js
export default defineConfig({
  base: 'http://localhost:3000/',
  server: {
    port: 3000,
    cors: true,
    origin: 'http://localhost:3000',
  },
});
```

【重要】注意：

1. base 提供资源绝对路径，避免相对路径带来的资源访问问题；
2. origin 提供资源绝对路径，避免相对路径带来的资源访问问题；
3. 需要将子应用沙箱关闭 `Garfish.run({ apps: [{ ..., sandbox: false }] })`
4. 子应用的副作用将会发生逃逸，在子应用卸载后需要将对应全局的副作用清除

### 5. 增加子应用独立运行兼容逻辑

:::tip
last but not least, 别忘了添加子应用独立运行逻辑，这能够让你的子应用脱离主应用独立运行，便于后续开发和部署。

:::

```js
// src/main.js
if (!window.__GARFISH__) {
  // 非微前端环境直接运行
  const vueInstance = createApp(App);
  vueInstance.mount(document.querySelector('#app'));
}
```



---
url: /guide/demo/angular.md
---

# angular 子应用

本节我们将详细介绍 angular 框架的应用作为子应用的接入步骤。[demo](https://github.com/modern-js-dev/garfish/tree/main/dev/app-angular)

## angular 子应用接入步骤

### 1. 插件安装

```bash npm2yarn
# 1. 安装 @angular-builders/custom-webpack:browser
npm install @angular-builders/custom-webpack:browser -D

# 2. 安装 @angular-builders/custom-webpack:dev-server
npm install @angular-builders/custom-webpack:dev-server -D
```

### 2. 修改 angular.json

1. 修改 \[packageName] > architect > build > builder

```json
// angular.json
"builder": "@angular-builders/custom-webpack:browser",
```

2. 修改 \[packageName] > architect > build > options

```json
// angular.json
"options": {
  "customWebpackConfig": {
    // 新增 webpack 配置
    "path": "./custom-webpack.config.js"
  },
  "index": "",
}
```

3. 修改 \[packageName] > architect > serve > builder

```json
// angular.json
"builder": "@angular-builders/custom-webpack:dev-server",
```

:::danger

1. 请注意，在 \[packageName] > architect > build > options 的配置中，index 属性我们设置为空，这是因为在 angular 13 中编译产物默认会带上 esm 标识，即 type=module, 即使打包产物是 umd 格式，这会导致 garfish 加载子应用失败；
2. index 置空后，编译产物会去除 es module 标识，子应用加载正常；

:::

### 3. 添加 webpack 配置文件

:::tip danger
【重要】注意：

1. libraryTarget 需要配置成 umd 规范；
2. globalObject 需要设置为 'window'，以避免由于不规范的代码格式导致的逃逸沙箱；
3. 如果你的 webpack 为 v4 版本，需要设置 jsonpFunction 并保证该值唯一（否则可能出现 webpack chunk 互相影响的可能）。若为 webpack5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同；
4. publicPath 设置为子应用资源的绝对地址，避免由于子应用的相对资源导致资源变为了主应用上的相对资源。这是因为主、子应用处于同一个文档流中，相对路径是相对于主应用而言的
5. 'Access-Control-Allow-Origin': '\*' 允许开发环境跨域，保证子应用的资源支持跨域。另外也需要保证在上线后子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）；

:::

```js
// custom-webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    libraryTarget: 'umd',
    globalObject: 'window',
    chunkLoadingGlobal: 'Garfish-demo-angular',
    publicPath: 'http://localhost:8080'
  },
  plugins: [
    new HtmlWebpackPlugin({
      filename: 'index.html',
      template: path.join(__dirname, 'src/index.html'),
      chunksSortMode: 'manual',
      chunks: ['styles', 'runtime', 'polyfills', 'scripts', 'vendors', 'main'],
      scriptLoading: 'defer',
    }),
  ],
  devServer: {
    headers: {
      'Access-Control-Allow-Origin': '*',
    },
  },
};

```

### 4. 更改 package.json 启动脚本

```json
  "scripts": {
    "builder": "@angular-builders/custom-webpack:dev-server"
  }
```

### 5. 入口文件处导出 provider 函数

```ts
  // src/main.ts
  import { enableProdMode, NgModuleRef } from '@angular/core';
  import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
  import { AppModule } from './app/app.module';
  import { environment } from './environments/environment';

  if (environment.production) {
    enableProdMode();
  }

  let app: void | NgModuleRef<AppModule>;

  async function render() {
    await platformBrowserDynamic()
      .bootstrapModule(AppModule)
      .catch((err) => console.error(err));
  }
  export const provider = ({ dom, basename, props}) => {
    return {
      render,
      destroy({ dom }) {
        const root = dom
          ? dom.querySelector('#root')
          : document.querySelector('#root');
      },
    };
  };
```

### 6. 根组件设置路由的 basename

:::info

1. 为什么要设置 basename？请参考 [issue](/issues/index.md#子应用拿到-basename-的作用)
2. 我们强烈建议使用从主应用传递过来的 basename 作为子应用的 basename，而非主、子应用约定式，避免 basename 后期变更未同步带来的问题。
3. 目前主应用仅支持 history 模式的子应用路由，[why](/issues/index.md#为什么主应用仅支持-history-模式)

:::

```ts
// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
import { ReactiveFormsModule } from '@angular/forms';
import { AppComponent } from './app.component';
import { TopBarComponent } from './topBar/topBar.component';
import { HomeComponent } from './home/home.component';
import { APP_BASE_HREF } from '@angular/common';

@NgModule({
  imports: [
    BrowserModule,
    ReactiveFormsModule,
    RouterModule.forRoot([
      { path: '/home', component: HomeComponent }
    ])
  ],
  providers: [{ provide: APP_BASE_HREF, useValue: '/examples/angular' }],
  declarations: [
    AppComponent,
    TopBarComponent,
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}
```

### 7. 增加子应用独立运行兼容逻辑

:::tip
last but not least, 别忘了添加子应用独立运行逻辑，这能够让你的子应用脱离主应用独立运行，便于后续开发和部署。

:::

```js
// src/main.ts
import { enableProdMode, NgModuleRef } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';

async function render() {
  await platformBrowserDynamic()
    .bootstrapModule(AppModule)
    .catch((err) => console.error(err));
}

if (!(window as any).__GARFISH__) {
  render();
}
```



---
url: /guide/concept/bridge.md
---

# bridge



## 介绍

Garfish bridge 是 `garfish` 提供的帮助用户降低接入成本的工具函数，它能自动提供 `provider` 函数所需的应用生命周期函数 `render` 和 `destroy` ，并实现框架不同版本的兼容。封装底层实现，降低接入成本和出错概率。

:::info

1. garfish bridge 应用在子应用接入场景；
2. 使用 garfish bridge 后不再需要显示提供 `render` 和 `destroy` 函数；
3. 目前 garfish 仅针对 react 和 vue 框架提供 bridge 函数支持，支持的版本分别为 react v16、v17、v18，vue v2、v3；
4. garfish bridge 暂未针对构建工具如 webpack、vite 提供相应的构建工具插件，我们后期会针对这块能力进行补全，请持续关注；

:::

## 工具包

### @garfish/bridge-react

[@garfish/bridge-react](https://www.npmjs.com/package/@garfish/bridge-react) 工具包是 garfish 为 react v16/v17 应用 提供的 bridge 工具函数包，其导出的 [reactBridge](/guide/concept/bridge.md#reactbridgefor-react-v16v17) 可用于 react v16/v17 子应用的接入，`@garfish/bridge-react` 的使用见 [demo](/guide/demo/react.md#react-v16v17-导出)。

### @garfish/bridge-react-v18

[@garfish/bridge-react-v18](https://www.npmjs.com/package/@garfish/bridge-react-v18) 工具包是 garfish 为 react v18 应用 提供的 bridge 工具函数包，其导出的 [reactBridge](/guide/concept/bridge.md#reactBridge) 可用于 react v18 子应用的接入，`@garfish/bridge-react-v18` 的使用见 [demo](/guide/demo/react.md#react-v18-导出)。

### @garfish/bridge-vue-v2

[@garfish/bridge-vue-v2](https://www.npmjs.com/package/@garfish/bridge-vue-v2) 工具包是 garfish 为 vue v2 应用 提供的 bridge 工具函数包，其导出的 [vueBridge](/guide/concept/bridge.md#vuebridge) 可用于 vue v2 子应用的接入，`@garfish/bridge-vue-v2` 的使用见 [demo](/guide/demo/vue.md#vue2-导出)。

### @garfish/bridge-vue-v3

[@garfish/bridge-vue-v3](https://www.npmjs.com/package/@garfish/bridge-vue-v3) 工具包是 garfish 为 vue v3 应用 提供的 bridge 工具函数包，其导出的 [vueBridge](/guide/concept/bridge.md#vuebridge) 可用于 vue v3 子应用的接入，`@garfish/bridge-vue-v3` 的使用见 [demo](/guide/demo/vue.md#vue3-导出)。

## 安装

```bash npm2yarn
npm install @garfish/bridge-react --save
```

```bash npm2yarn
npm install @garfish/bridge-vue-v2 --save
```

```bash npm2yarn
npm install @garfish/bridge-vue-v3 --save
```

## reactBridge(for react v16/v17/v18)

reactBridge 是 `@garfish/bridge-react` 工具包为 react 子应用提供的 bridge 工具函数。

:::info

* 针对 react v16/v17 子应用，请使用 `@garfish/bridge-react` 工具包
* 针对 react v18 子应用，请使用 `@garfish/bridge-react-v18` 工具包

:::

reactBridge 是 `@garfish/bridge-react` 或  `@garfish/bridge-react-v18` 工具包为 react 子应用提供的 bridge 工具函数。

### Type

```ts
function reactBridge(userOpts: Options): (
  appInfo: any,
  props: any,
) => Promise<{
  render: (props: any) => any;
  destroy: (props: any) => any;
  update: (props: any) => any;
}>;
```

### 示例

> 可访问 [react16 子应用](https://github.com/modern-js-dev/garfish/tree/main/dev/app-react-16)、 [react17 子应用](https://github.com/modern-js-dev/garfish/tree/main/dev/app-react-17)、[react18 子应用](https://github.com/modern-js-dev/garfish/tree/main/dev/app-react-18) 查看完整 demo

```ts
import { reactBridge } from '@garfish/bridge-react';
import RootComponent from './components/root';
import ErrorComponent from './components/ErrorBoundary';

export const provider = reactBridge({
  el: '#root',
  rootComponent: RootComponent,
  errorBoundary: () => <ErrorComponent />,
});
```

```ts
import { reactBridge } from '@garfish/bridge-react-v18';
import RootComponent from './components/root';
import ErrorComponent from './components/ErrorBoundary';

export const provider = reactBridge({
  el: '#root',
  rootComponent: RootComponent,
  errorBoundary: () => <ErrorComponent />,
});
```

### 参数

`Options`

* &#x20;el&#x20;

  * Type: `string`
  * 非必传
  * 子应用挂载点
    * 若子应用构建为 `JS` 入口时，不需要传挂载点，Bridge 将会以子应用的渲染节点作为挂载点；
    * 若子应用构建成 `HTML` 入口时，则直接传入选择器，bridge 内部通过 `dom.querySelector` 来基于子应用的 `dom` 来找到挂载点；

* &#x20;rootComponent&#x20;

  * Type：`React.ComponentType`
  * 此参数和 `loadRootComponent` 至少传一个
  * 当前应用的顶层 React 组件，该组件中将接受到 garfish 传递的 appInfo 应用相关参数：
    ```ts
    // components/root.tsx
    const RootComponent = ({ appName, basename, dom, props }) => { ... }
    ```
  * 当同时传入了 `loadRootComponent` 参数时，`rootComponent` 参数将失效，且 `rootComponent` 组件不会默认接收到 garfish 传递的子应用相关参数；

* &#x20;loadRootComponent&#x20;

  * Type：`loadRootComponentType = (opts: Record<string, any>) => Promise<ComponentType>;`
  * 此参数和 `rootComponent` 至少传一个
  * 当前应用的顶层 React 组件，该组件中将接收到 garfish 传递的子应用相关参数：

  ```ts
  // components/root.tsx
  const RootComponent = ({ appName, basename, dom, props }) => { ... }
  ```

  * `loadRootComponent` 是一个函数，返回一个 Promise 对象，resolve 后需要返回当前 React 应用的顶层组件，该顶层组件含义与 `rootComponent` 含义相同。当需要在 render 前进行异步操作时，可使用 `loadRootComponent` 加入副作用逻辑。
  * `loadRootComponent` 将默认接收到 garfish 传递的子应用相关参数：

  ```ts
   import { reactBridge } from "@garfish/bridge-react";
   export const provider = reactBridge({
     ...,
     loadRootComponent: ({ basename, dom, appName, props }) => {
        // do something async
       return Promise.resolve(() => <RootComponent basename={ basename } />);
     }
   });
  ```

  此时，`RootComponent` 接收到的参数取决于此处 `loadRootComponent` 传递的参数。

  * 当同时传入了 `rootComponent` 参数时，`loadRootComponent` 的优先级更高， `rootComponent` 将失效；

* &#x20;errorBoundary&#x20;

  * Type：`errorBoundary: (caughtError: boolean, info: string, props: any) => ReactNode | null;`
  * 非必传
  * 设置应用的 errorBoundary 组件，`errorBoundary` 是一个函数，并在子应用发生错误时触发，该函数将传递 error 报错信息及报错相关应用堆栈信息：

  ```ts
   import { reactBridge } from "@garfish/bridge-react";
   export const provider = reactBridge({
     ...,
     errorBoundary: ( error, info ) => <ErrorComponent />,
   });
  ```

## vueBridge(for vue v2)

:::info
针对 vue v2 子应用，请使用 `@garfish/bridge-vue-v2` 工具包。

:::

vueBridge 是 `@garfish/bridge-vue-v2` 工具包为 vue v2 子应用提供的 bridge 工具函数。

### 类型

```ts
function vueBridge(userOpts: Options): (
  appInfo: any,
  props: any,
) => Promise<{
  render: (props: any) => any;
  destroy: (props: any) => any;
  update: (props: any) => any;
}>;
```

### 示例

> 可访问 [vue2 子应用](https://github.com/modern-js-dev/garfish/tree/main/dev/app-vue-2) 查看完整 demo

```ts
import { vueBridge } from '@garfish/bridge-vue-v2';
import store from './store';
import App from './App.vue';
import Home from './components/Home.vue';

Vue.use(VueRouter);
Vue.config.productionTip = false;

function newRouter(basename) {
  const router = new VueRouter({
    mode: 'history',
    base: basename,
    routes: [{ path: '/home', component: Home }],
  });
  return router;
}

export const provider = vueBridge({
  rootComponent: App,
  // 可选，注册 vue-router或状态管理对象
  appOptions: ({ basename, dom, appName, props }) => {
    // pass the options to Vue Constructor. check https://vuejs.bootcss.com/api/#%E9%80%89%E9%A1%B9-%E6%95%B0%E6%8D%AE
    return {
      el: '#app',
      router: newRouter(basename),
      store,
    };
  }
});
```

### 参数

`Options`

* &#x20;rootComponent&#x20;

* Type：`vue.Component`

* 非必传。此参数和 `loadRootComponent` 至少传一个

* 当前应用的顶层 Vue 组件，该组件中将接受到 garfish 传递的子应用相关参数：
  ```ts
  // components/root.tsx
  const RootComponent = ({ appName, basename, dom, props, appInfo}) => { ... }
  ```

* 当同时传入了 `loadRootComponent` 参数时，`rootComponent` 将失效，且 `rootComponent` 组件不会默认接受到 garfish 传递的子应用相关参数；

* &#x20;loadRootComponent&#x20;

  * Type：`loadRootComponentType = (opts: Record<string, any>) => Promise<ComponentType>;`

  * 非必传。此参数和 `rootComponent` 至少传一个

  * 当前应用的顶层 Vue 组件，该组件中实例的 data 对象中将接收到 garfish 传递的子应用相关参数

  * `loadRootComponent` 是一个函数，返回一个 Promise 对象，resolve 后需要返回当前 Vue 应用的顶层组件，该顶层组件含义与 `rootComponent` 含义相同。当需要在 render 前进行异步操作时，可使用 `loadRootComponent` 加入副作用逻辑。

  * `loadRootComponent` 将默认接收到 garfish 传递的子应用相关参数：

  ```ts
   import { vueBridge } from "@garfish/bridge-vue-v2";
   export const provider = vueBridge({
     ...,
     loadRootComponent: ({ appName, basename, dom, props, appInfo }) => {
       // do something async
       return Promise.resolve(App);
     }
   });
  ```

  * 当同时传入了 `rootComponent` 参数时，`loadRootComponent` 的优先级更高， `rootComponent` 将失效；

* &#x20;appOptions&#x20;

  * Type: `appOptions: (opts: Record<string, any>) => Record<string, any> | Record<string, any>`
  * 非必传
  * 作为函数时，接收 garfish 传递的子应用相关参数并返回用来实例化 Vue 应用的对象参数，也可作为对象类型直接返回用来实例化 Vue 应用的对象参数。实例化完成后，garfish 子应用相关参数将会自动注入到组件实例的 `data` 对象中。
  * `appOptions` 参数将直接透传为 Vue 构造函数实例化时的初始化参数 new Vue(appOptions)，此时参数类型与 [vue](https://vuejs.bootcss.com/api/#%E9%80%89%E9%A1%B9-%E6%95%B0%E6%8D%AE) 保持一致。若未传递 `appOptions` 参数，则将自动提供 vue2 应用 `render` 函数用于渲染：`render: (h) => h(opts.rootComponent)`。
  * 若需要指定子应用挂载点，可在此参数中指定：`appOptions: { el: '#app', ...}`，若未指定 `el` 参数，将默认使用全局挂载点。

:::tip
需要注意的是，`appOpitons` 中并不会默认包含路由或状态逻辑的处理，可显示在 `appOpitons` 中传递路由参数信息。

:::

```js
import { vueBridge } from '@garfish/bridge-vue-v2';
export const provider = vueBridge({
  rootComponent: App,
  appOptions: ({ basename, dom, appName, props, appInfo }) => {
    // pass the options to Vue Constructor. check https://vuejs.bootcss.com/api/#%E9%80%89%E9%A1%B9-%E6%95%B0%E6%8D%AE
    return {
      el: '#app',
      router: newRouter(basename),
      store,
    };
  }
});
```

* &#x20;handleInstance&#x20;

  * Type: ` handleInstance: (vueInstance: InstanceType<vue.VueConstructor>, opts: optionsType) => void;`
  * 非必传
  * 处理 app 实例对象的函数，接受创建的 app 实例对象及 garfish 子应用相关参数，可自定义处理逻辑如路由注册或状态管理等相关能力。

## vueBridge(for vue v3)

:::info
针对 vue v3 子应用，请使用 `@garfish/bridge-vue-v3` 工具包。

:::

vueBridge 是 `@garfish/bridge-vue-v3` 工具包为 vue v3 子应用提供的 bridge 工具函数。

### 类型

```ts
function vueBridge(userOpts: Options): (
  appInfo: any,
  props: any,
) => Promise<{
  render: (props: any) => any;
  destroy: (props: any) => any;
  update: (props: any) => any;
}>;
```

### 示例

> 可访问 [vue v3 子应用](https://github.com/modern-js-dev/garfish/tree/main/dev/app-vue-3) 查看完整 demo

```ts
import { createRouter, createWebHistory } from 'vue-router';
import { stateSymbol, createState } from './store.js';
import App from './App.vue';
import Home from './components/Home.vue';
import { vueBridge } from '@garfish/bridge-vue-v3';

function newRouter(basename) {
  const router = createRouter({
    history: createWebHistory(basename),
    routes: [{ path: '/home', component: Home }],
  });
  return router;
}

export const provider = vueBridge({
  rootComponent: App,
  // 可选，注册 vue-router或状态管理对象
  handleInstance: (vueInstance, { basename, dom, appName, props, appIndfo }) => {
    vueInstance.use(newRouter(basename));
    vueInstance.provide(stateSymbol, createState());
  },
});
```

### 参数

`Options`

* &#x20;rootComponent&#x20;

* Type：`vue.Component`

* 非必传。此参数和 `loadRootComponent` 至少传一个

* 当前应用的顶层 Vue 组件，该组件中将接受到 garfish 传递的子应用相关参数：
  ```ts
  // components/root.tsx
  const RootComponent = ({ appName, basename, dom, props, appInfo}) => { ... }
  ```

* 当同时传入了 `loadRootComponent` 参数时，`rootComponent` 将失效，且 `rootComponent` 组件不会默认接受到 garfish 传递的子应用相关参数；

* &#x20;loadRootComponent&#x20;

  * Type：`loadRootComponentType = (opts: Record<string, any>) => Promise<ComponentType>;`

  * 非必传。此参数和 `rootComponent` 至少传一个

  * 当前应用的顶层 Vue 组件，该组件中实例的 data 对象中将接收到 garfish 传递的子应用相关参数

  * `loadRootComponent` 是一个函数，返回一个 Promise 对象，resolve 后需要返回当前 Vue 应用的顶层组件，该顶层组件含义与 `rootComponent` 含义相同。当需要在 render 前进行异步操作时，可使用 `loadRootComponent` 加入副作用逻辑。

  * `loadRootComponent` 将默认接收到 garfish 传递的子应用相关参数：

  ```ts
   import { vueBridge } from "@garfish/bridge-vue-v3";
   export const provider = vueBridge({
     ...,
     loadRootComponent: ({ appName, basename, dom, props, appInfo }) => {
       // do something async
       return Promise.resolve(App);
     }
   });
  ```

  * 当同时传入了 `rootComponent` 参数时，`loadRootComponent` 的优先级更高， `rootComponent` 将失效；

* &#x20;appOptions&#x20;

  * Type: `appOptions: (opts: Record<string, any>) => Record<string, any> | Record<string, any>`
  * 非必传
  * 作为函数时，接收 garfish 传递的子应用相关参数并返回用来实例化 Vue 应用的对象参数，也可作为对象类型直接返回用来实例化 Vue 应用的对象参数。实例化完成后，garfish 子应用相关参数将会自动注入到组件实例的 `data` 对象中。
  * 在 Vue3 中，`appOptions` 参数将直接透传给 `createApp` 函数调用： `createApp(appOptions)`，此时参数类型与 [createApp](https://vuejs.org/api/application.html#createapp) 保持一致。若未传递 `appOptions` 参数，则将直接调用 `createApp(rootComponent)` 创建根组件。
  * 若需要指定子应用挂载点，可在此参数中指定：`appOptions: { el: '#app', ...}`，若未指定 `el` 参数，将默认使用全局挂载点。

:::tip
需要注意的是，`appOptions` 中并不会默认包含路由或状态逻辑的处理，可通过 `handleInstance` 函数拿到创建的 vue 实例对象后进行路由注册。

:::

* &#x20;handleInstance&#x20;

  * Type: `handleInstance: (vueInstance: vue.App, opts: optionsType) => void;`
  * 非必传
  * 处理 app 实例对象的函数，接受创建的 app 实例对象及 garfish 子应用相关参数，可自定义处理逻辑如路由注册或状态管理等相关能力。

```js
import { vueBridge } from '@garfish/bridge-vue-v3';
export const provider = vueBridge({
  rootComponent: App,
  // 获取 vue 实例并进行路由注册和状态注册
  handleInstance: (vueInstance, { basename, dom, appName, props, appInfo }) => {
    vueInstance.use(newRouter(basename));
    vueInstance.provide(stateSymbol, createState());
  },
});
```



---
url: /guide/concept/cache.md
---

# 缓存机制

`Garfish` 的设计的初衷并不是为了取代 `iframe`，而是为了将一个单体应用拆分成多个子应用后也能保证应用一体化的使用体验，`Garfish` 为了提升应用的渲染性能，提供了缓存渲染模式。

缓存的形式分为两种，一种是缓存 `App` 的实例，缓存 `App` 的实例比较容易理解，`Garfish` 在通过 `loadApp` 加载子应用后可以保留 `App` 的实例，另外一种则是缓存子应用的执行上下文，第二遍执行时不执行所有代码来提升整体的渲染速度。

## 提升渲染速度

为什么 `Garfish` 的子应用需要提供 `provider` 函数呢？原因是通过提供 `provider` 生命周期，我们可以尽可能的优化渲染速度。

- 在应用销毁时触发对应框架应用的销毁函数，以达到对框架类型的销毁操作，应用中的一些销毁 `hook` 也可以正常触发
- 在第二次应用加载时可以启动缓存模式
  - 在应用第一次渲染时的路径为，`html` 下载=> `html` 拆分=> 渲染 `dom` => 渲染 `style` => 执行 `JS` => 执行 `provider` 中的函数
  - 在第二次渲染时可以将整个渲染流程简化为，还原子应用的 `html` 内容=> 执行 `provider` 中的渲染函数。因为子应用的真实执行环境并未被销毁，而是通过 `render` 和 `destroy` 控制对应应用的渲染和销毁
- 避免内存泄漏
  - 由于目前 `Garfish` 框架的沙箱依赖于浏览器的 `API`，无法做到物理级别的隔离。由于 `JavaScript` 语法的灵活性和闭包的特性，第二次重复执行子应用代码可能会导致逃逸内容重复执行
  - 采用缓存模式时，将不会执行所有代码，仅执行 `render` ，将会避免逃逸代码造成的内存问题

> 缓存模式下的弊端

- 启动缓存模式后也存在一定弊端，第二遍执行时 `render` 中的逻辑获取的还是上一次的执行环境并不是一个全新的执行环境，下面代码中在缓存模式时和非缓存模式不同的表现
  - 在缓存模式中，多次渲染子应用会导致 `list` 数组的值持续增长，并导致影响业务逻辑
  - 在非缓存模式中，多次渲染子应用 `list` 数组的长度始终为 `1`
- `Garfish` 框架无法有效区分哪些副作用需要销毁
  - 在缓存模式中并不会执行子应用的所有代码，只会还原子应用的上下文并执行子应用的 `render` 函数，因此无法区分哪些副作用是实际应用 `render` 过程中创建的还是其他基础库造成的
  - 目前 `Garfish` 框架在缓存模式下仅会收集和清除：样式副作用、环境变量

```js
const list = [];

export const provider = () => {
  return {
    render: ({ dom, basename }) => {
      list.push(1);
      ReactDOM.render(
        <React.StrictMode>
          <App basename={basename} />
        </React.StrictMode>,
        dom.querySelector('#root'),
      );
    },

    destroy: ({ dom, basename }) => {
      ReactDOM.unmountComponentAtNode(dom.querySelector('#root'));
    },
  };
};
```

具体使用如何使用缓存模式请参考：[Garfish.loadApp](/api/loadApp)

## 缓存 App 实例

手动加载提供了 `cache` 功能，以便复用 `app`，避免重复的编译代码造成的性能浪费，在 `Garfish.loadApp` 时，传入 `cache` 参数就可以。

 例如下面的代码：

```js
const app1 = await Garfish.loadApp('appName', {
  cache: true,
});

const app2 = await Garfish.loadApp('appName', {
  cache: true,
});

console.log(app1 === app2); // true
```

实际上，对于加载的 `promise` 也会是同一份，例如下面的 demo

```js
const promise1 = Garfish.loadApp('appName', {
  cache: true,
});

const promise2 = Garfish.loadApp('appName', {
  cache: true,
});

console.log(promise1 === promise2); // true

const app1 = await promise1;
const app2 = await promise2;
console.log(app1 === app2); // true
```



---
url: /guide/concept/lifecycle.md
---

# 生命周期

`Garfish` 应用的生命周期可以归结为：加载、渲染、销毁 三个阶段，因此 `Garfish` 应用的生命周期也是围绕着这三个阶段而展开的。应用的加载主要是通过 [Garfish.loadApp](../../api/loadApp.md)，通过 `loadApp` API 会自动创建应用的实例，可以通过应用实例上的 `mount` 和 `show` 方法对应用进行渲染，通过 `unmount` 和 `hide` 方法对应用进行销毁，用户在实际使用的过程中通过 [Garfish.run](../../api/run.md)会发现当路由发生变化时符合加载条件的应用会自动加载渲染，实际上是 [`Garfish Router Plugin`](./router.md) 通过监听路由变化来触发 `loadApp` 和 `mount` 自动完成应用的加载、渲染、销毁。

<img
  src="https://user-images.githubusercontent.com/27547179/165056974-f40d790e-3db1-4aea-b2db-5d3618a150d5.png"
  width="400"
/>

### mount

app.mount 做了哪些事情

1. 创建 `app` 容器并添加到文档流上
2. 编译子应用的代码
3. 拿到子应用的 `provider`
4. 调用 `app.options.beforeMount` 钩子
5. 调用 `provider.render`
6. 将 `app.display` 和 `app.mounted` 设置为 `true`
7. 将 `app` set 到 `Garfish.activeApps` 中
8. 调用 `app.options.afterMount` 钩子
9. 如果渲染失败，`app.mount` 会返回 `false`，否则渲染成功会返回 `true`，你可以根据返回值做对应的处理。

### unmount

app.unmount 做了哪些事件

1. 调用 `app.options.beforeUnmount` 钩子
2. 调用 `provider.destroy`
3. 清除编译的副作用
4. 将 `app` 的容器从文档流上移除
5. 将 `app.display` 和 `app.mounted` 设置为 `false`
6. 在 `Garfish.activeApps` 中移除当前的 `app` 实例
7. 调用 `app.options.afterUnmount` 钩子
8. 同上，可以根据返回值来判断是否卸载成功。

### show

app.show 做了哪些事件

1. 将 `app` 的容器添加到文档流上
2. 调用 `provider.render`
3. 将 `app.display` 设置为 `true`
4. 同上，可以根据返回值来判断是否渲染成功。

### hide

app.hide 做了哪些事件

1. 调用 `provider.destroy`
2. 将 `app` 的容器从文档流上移除
3. 将 `app.display` 设置为 `false`
4. 同上，可以根据返回值来判断是否隐藏成功。



---
url: /guide/concept/router.md
---

# 路由机制

为什么需要 `Router`，其实从现在主流的前端框架可以发现他们都是可以通过路由驱动的，开发者只需要配置路由的 `map` 规则，即可在进入指定路由后载入子应用。这无疑大大降低了单页应用的复杂度，微前端上我们也可以借用单页应用的路由驱动模式，将每个子应用作为组件，并且只托管子应用的根路由，二级及以下路由交由子应用自己负责。其他比较复杂的情况，可以通过与手动载入配合。

![image](https://user-images.githubusercontent.com/27547179/165110838-2f907b10-40b4-4e00-afab-808ef08d1570.png)

`Garfish Router` 如何处理路由，通过上面理想的路由模式案例发现，微前端应用拆分成子应用后，子应用路由应具备自治能力，可以充分的利用应用解耦后的开发优势，但与之对应的是应用间的路由可能会发生冲突、两种路由模式下可能产生用户难以理解的路由状态、无法激活不同前端框架的下带来的视图无法更新等问题。

> 目前 `Garfish` 主要提供了以下三条策略

- 提供 `Router Map`，减少典型中台应用下的开发者理解成本
- 为不同子应用提供不同的 `basename` 用于隔离应用间的路由抢占问题
- 路由发生变化时能准确激活并触发应用视图更新

## `Router Map` 降低开发者理解成本

在典型的中台应用中，通常可以将应用的结构分为两块，一块是菜单另一块则是内容区域，依托于现代前端 Web 应用的设计理念的启发，通过提供路由表来自动化完成子应用的调度，将公共部分作为拆离后的子应用渲染区域。

## 提供 basename

在自动挂载模式下 `Garfish` 会根据用户提供的 `activeWhen` 自动计算出子应用的 basename，子应用使用该 `basename` ，子应用设置 basename 后可以保证应用间的路由互不影响且能达到多个微前端应用组合成单个 `SPA` 应用的体验，并且这些微前端应用能具备自己的路由。

## 如何有效的触发不同应用间的视图更新

目前主流框架实现路由的方式并不是监听路由变化触发组件更新，让开发者通过框架包装后的 API 进行跳转，并内部维护路由状态，在使用框架提供 API 方法发生路由更新时，内部状态发生变更触发组件更新。

由于框架的路由状态分别维护在各自的内部，那么如何保证在路由发生变化时能及时有效的触发应用的视图更新呢，答案是可以的，目前主要有两种实现策略：

1. 收集框架监听的 `popstate` 事件
2. 主动触发 `popstate` 事件
   因为目前支持 SPA 应用的前端框架都会监听浏览器后退事件，在浏览器后退时根据路由状态触发应用视图的更新，那么其实也可以利用这种能力主动触发应用视图的更新，可以通过收集框架的监听事件，也可以触发 `popstate` 来响应应用的 `popstate` 事件



---
url: /guide/concept/buildConfig.md
---

# 构建配置

在 **「快速开始」** 章节可以发现，`Garfish` 针对不同的构建工具：`webpack`、`vite` 都要求其配置一些构建配置，那么这些构建配置分别在 `Garfish` 微前端应用中起到什么作用呢，「构建配置」这一章节主要是希望能够给帮助你了解背后这些构建配置带来的作用，下面的内容主要以 `webpack` 构建配置为例：

```js
// webpack.config.js
{
  output: {
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // 请求确保每个子应用该值都不相同，否则可能出现 webpack chunk 互相影响的可能
    // webpack 5 使用 chunkLoadingGlobal 代替，若不填 webpack 5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同
    jsonpFunction: 'vue-app-jsonpFunction',
    // 保证子应用的资源路径变为绝对路径，避免子应用的相对资源在变为主应用上的相对资源，因为子应用和主应用在同一个文档流，相对路径是相对于主应用而言的
    publicPath: 'http://localhost:8000',
  },
}
```

## libraryTarget

在构建配置中通过 `libraryTarget` 可以将项目的产物分别构建成不同规范的产物：`umd`、`commonjs` 等规范的产物，实际 `Garfish` 希望子应用导出的是 `commonjs` 的产物，但是为了避免后续 `Garfish` 采用其他规范的产物，因此通常让微前端子应用构建成 `umd` 的产物，那么 `Garfish` 为什么希望子应用导出的是 `commonjs` 的产物呢？主要是解决两个问题：

1. 获取 `provider` 渲染协议
2. 进行依赖注入和共享

为什么设置为 `commonjs` 协议后，`Garfish` 框架能够获取 `provider` 协议和进行依赖注册和共享呢，这一切都要从 `commonjs` 的规范讲起，如果了解过 `commonjs` 实现原理的一定对下面这段代码非常熟悉：

```js
let code = `(function(exports,require,module,__dirname,__filename){

})`;
vm.runInThisContext(fn).call(module.exports, module.exports, req, module);
```

在 `node` 环境中拥有 `exports`、`require` ... 这几个全局环境变量，通过这些环境能够完成模块的加载，完成内容的导出和载入，那么同时也能够利用 `commonjs` 的机制在代码运行时注入 `exports`、`require` 环境变量从而实现控制子应用获取依赖和拿到子应用导出内容的目的

```js
// 实际代码
let code = ``;
new Function('require', 'exports', code)(fakeRequire, fakerExports);
```

## globalObject

`globalObject` 的配置主要与 `Garfish` 的 `sandbox` 执行代码的机制有关，可以参考 [沙箱机制的异常 case 逃逸](./sandbox.md#特殊-case)

## jsonpFunction

> webpackjsonp 是什么？

`webpack` 使用 `webpackjsonp` 来解决分 chunk 之后的加载问题，在 webpack 5 中采用 chunkLoadingGlobal 代替。

`webpackjsonp` 是一个全局变量，用于存储 chunk 的信息。

如下图：

![image](https://user-images.githubusercontent.com/27547179/167364472-8e3ce4b9-94b3-490f-a4bf-b904579ea3a1.png)

> `jsonpFunction` 配置的作用

`jsonpFunction` 的配置主要也与沙箱的机制有关， `Garfish` 的沙箱子应用的执行上下文 `window` 主要来自于主应用，当主应用与子应用都是用相同的 `key` 作为子应用 `jsonp` 存储 `chunk` 的方式时，子应用的 `chunk` 可能会受到主应用和其他应用的影响，因此通过 `jsonpFunction` 配置能够避免应用间的 `chunk` 互相应用

## publicPath

通过 `publicPath` 配置将微前端子应用的资源路径转换成绝对路径，为什么需要将子应用的资源路径转换成绝对路径呢？

- 子应用在独立运行时，使用相对路径的接口时，接口请求的路径是，当前页面域名+相对路径
- 但是在主应用时，子应用使用相对路径的接口，请求的路径按道理来说还是，当前域名+相对路径

当在微前端的场景下如果 `Garfish` 让子应用走「当前域名+相对路径」会发生更多的异常请求（`hmr` 热更新、`websocket`、`server worker` ...），因为子应用的域名并不一定是与主应用一致，因此 `Garfish` 框架会对相对路径的资源和请求去进行修正，修正的参照物为基础域名为子应用的路径，在本地开发时可能是正常的，但是发到线上出现问题，原因在于发布到线上之后，子应用的入口有可能会走 `CDN`。因此参照的基础路径就变为了 CDN 前缀。那么此时子应用的相对路径请求就变为了 `CDN` 前缀。这一块做了很多权衡，因为 `hmr`、`websocket`、`server worker` 这些内容可能难以被用户控制，所以默认走的还是修正模式。



---
url: /guide/concept/sandbox.md
---

# 沙箱机制

## Changelog

| 版本 | 日期      | 修订人      | ChangeLog        |
| ---- | --------- | ----------- | ---------------- |
| v0.1 | 2022-4-20 | zengkunpeng | 沙箱机制文章开源 |
| v0.2 | 2022-4-29 | zhouxiao    | 调整 DOM 副作用  |

## 背景

在微前端的场景，由于多个独立的应用被组织到了一起，在没有类似 `iframe` 的原生隔离下，势必会出现冲突，如全局变量冲突、样式冲突，这些冲突可能会导致应用样式异常，甚至功能不可用。所以想让微前端达到生产可用的程度，让每个子应用之间达到一定程度隔离的沙箱机制是必不可少的。

此外沙箱功能还需要满足多实例的场景，先来了解一下什么是微前端里的多实例。

![image](https://user-images.githubusercontent.com/27547179/164134100-2c4d311e-4849-4ca4-a965-de1ff1a980d0.png)

## 手动执行代码

常规的脚本加载，是通过 `script` 标签去执行的，如

```html
// 内连
<script>
    //code
</sript>

// 外链
<script src="xxx.js"/>
```

要实现沙箱，因为需要控制沙箱的开启和关闭，我们就需要精确掌握脚本的执行时机，所以我们需要寻找一种合适的能手动执行代码的方法

### eval

`The eval() function evaluates JavaScript code represented as a string.`

首先我们想到的是 eval，由于 eval 有安全、性能等问题，同时也不利于调试，所以在以前我们听到的都是不推荐使用 eval 这个 api。
但是在微前端的沙箱场景，eval 确实是一个比较好的解决方案，比如 `qiankun` 就采用了 `eval` 作为代码执行器。

### new Function

`The Function constructor creates a new Function object. In JavaScript, every function is actually a Function object.`

`new Function` 通过传入一个 `string` 作为函数的的主体同时返回一个新函数，可以作为 `eval` 的一个替代品

### 对比

对比 `eval` ，有两点比较重要的不同：

- 不能访问当前环境的变量，但是可以访问全局变量，安全性更高
- 仅需要处理传入的字符串一次，后面重复执行都是同一个函数，而 eval 需要每次都处理，性能更高

```js
var str = '';
for (let i = 0; i < 100; i++) {
  str += `var test_${i} = ${i};\n`;
}
console.time('eval exec');
eval(str);
console.timeEnd('eval exec');
console.time('eval exec 2');
eval(str);
console.timeEnd('eval exec 2');

console.time('fn exec');
var fn = new Function(str);
fn();
console.timeEnd('fn exec');

console.time('fn exec 2');
fn();
console.timeEnd('fn exec 2');
```

运行结果

```javascript
eval exec: 0.251953125 ms
eval exec 2: 0.207763671875 ms
fn exec: 0.1708984375 ms
fn exec 2: 0.001708984375 ms
```

## 实现隔离

上面我们已经找到一种方式比较好的方式去做隔离，假设我们现在通过 `new function` 封装了一个 `execScript` 函数，能够执行传入的字符串。

```javascript
execScript(code:string);
```

那我们下一步就是实现隔离，让这个 `execScript` 的函数和沙箱结合起来。

结合 `Garfish` 的实现来具体看看，目前有两种隔离的方案，一种是快照沙箱，一种是 `vm` 沙箱。

### 快照沙箱

顾名思义，即在某个阶段给当前的运行环境打一个快照，再在需要的时候把快照恢复，从而实现隔离。

类似玩游戏的 `SL` 大法，在某个时刻保存起来，操作完毕再重新 `Load`，回到之前的状态。

#### 实现思路

我们假设有个 `Sandbox` 的类

```js
class Sandbox {
    private snapshotOriginal
    private snapshotMutated
    activate: () => void;
    deactivate: () => void;
}

const sandbox = new Sandbox();
sandbox.activate();
execScript(code)；
sandbox.deactivate();
```

关键的方法就是在 `activate` 和 `deactivate` 两个方法上

1. 在 `activate` 的时候遍历 `window` 上的变量，存为 `snapshotOriginal`
2. 在 `deactivate` 的时候再次遍历 `window` 上的变量，分别和 `snapshotOriginal` 对比，将不同的存到 `snapshotMutated` 里，将 `window` 恢复回到 `snapshotOriginal`
3. 当应用再次切换的时候，就可以把 `snapshotMutated` 的变量恢复回 `window` 上，实现一次沙箱的切换。

### VM 沙箱

`VM` 沙箱使用类似于 `node` 的 `vm` 模块，通过创建一个沙箱，然后传入需要执行的代码。

```javascript
class VMSandbox {
    execScript: (code: string) => void;
    destory: () => void;
}

const sandbox = new VMSandbox();
sandbox.execScript(code)；

const sandbox2 = new VMSandbox();
sandbox2.execScript(code2)；
```

### Proxy

在日常的编程里，会经常用到 `window`、`document` 这类全局对象，所以我们可以去改写 `new function` 里的这些对象，同时收集代码对这些对象的操作，把变更放到一个局部变量，就不会影响全局的 `window`。

结合 `ES6` 的新 `API`：`Proxy`，我们可以比较好的做到这点，我们来实现以下 `execScript`：

```javascript
const varBox = {};
const fakeWindow = new Proxy(window, {
  get(target, key) {
    return varBox[key] || window[key];
  },
  set(target, key, value) {
    varBox[key] = value;
    return true;
  },
});
const fn = new Function('window', code);
fn(fakeWindow);
```

这样我们就可以实现一个简单的沙盒功能。
不过 `Proxy` 有兼容性问题，`Garfish` 最初使用的是 `Proxy` 的 `Polyfill`，虽然不能 100% `Polyfill`，但是 get 和 set 能够满足我们的大多数场景。
然而 `ProxyPolyfill` 的方案实际让我们踩了很多坑，最终决定放弃 `Polyfill` 的方案，采用优先使用 `Proxy` 而不支持 `Proxy` 将降级到快照沙箱。

#### with 语句

虽然上面已经实现了一个简单的沙箱，但是要达到生产环境可用还是远远不够的，在实际的场景里，如下面的一段 `JS`，在浏览器 `script` 标签里执行是没问题的，但是在沙箱里就会报错

```javascript
window.$CONFIG = { a: true }; // 能被成功写到沙箱里

if ($CONFIG.a) {
  // Uncaught ReferenceError: $CONFIG is not defined
  console.log(1);
}
```

因此我们需要用到另一个之前也是被大家建议不要使用的 `api：with`

> The with statement extends the scope chain for a statement.

来改进一下我们的沙箱，使用 with 语句包裹起来

```javascript
const varBox
const fakeWindow = new Proxy(window, {
    get(target, key) {
        if (overides[key]) {
            return ;
        }
        return varBox[key] || window[key];
    },
    set(target, key, value) {
        varBox[key] = value;
        return true;
    }
})
const fn = new Function('window', `
    with(window)
        window.localstorage.setItem('1',123);
    }`
);
fn(fakeWindow);
```

这就可以正常运行了。

#### 异步脚本

在实际环境里，还可能会有异步脚本的加载，如动态 `import`，在 `React` 里是 `Loadable`、`Vue` 里是动态组件，都会让 `webpack` 编译出单独的一个异步脚本，这种脚本是通过 `script` 标签去插入的，从而从沙箱里逃逸。`Garfish` 通过劫持 `document` 的 `createElement` 方法，判断如果是创建 `script` ，则阻止原生行为，通过 `fetch` 去拉取 `script` 的内容，再放到沙箱里执行。
但是这样会带来一个问题，`xhr` 有跨域限制，而 `script` 没有，有一定潜在的风险。

#### 特殊 CASE

- var 导致的逃逸

```javascript
var $CONFIG = { a: true }; // 能被成功写到沙箱里

if ($CONFIG.a) {
  // Uncaught ReferenceError: $CONFIG is not defined
  console.log(1);
}
```

通过 `with + proxy` 可以解决这个问题，因为前面说过 `with` 是通过 `in` 来判断是否在当前作用域内的，而 `Proxy` 的 `has` 能重写 `in `的返回，（而 Proxy 的 Polyfill 无法 Polyfill has 因为无法使用 Proxy 的 ）我们再改写一下沙箱的代码，这段代码就运行成功了。

```javascript
const varBox
const fakeWindow = new Proxy(window, {
    get(target, key) {
        return varBox[key] || window[key] ;
    },
    set(target, key, value) {
        varBox[key] = value;
        return true;
    }，
    has(target, key) {
        return true;
    }
})
const fn = new Function('window', `
    with(window){
        code
        var a = 123;
        a;
    }`
);
fn(fakeWindow);
```

不过这也会带来另一个问题，任何的 `'xxx'` in `window` 都会返回 `true`，明显不符合预期，所以我们做了两个独立的 `proxy`， 一个来作为 `with` 来解决 `var` 的问题，一个就是针对 `window` 做 `proxy`。

```javascript
const varBox = {};
const get = (target, key) => {
  if (key === 'window') {
    return fakeWindow;
  }
  return varBox[key] || window[key];
};

const set = (target, key, value) => {
  varBox[key] = value;
  return true;
};

const has = (target, key) => {
  return true;
};

const context = new Proxy(window, {
  get,
  set,
  has,
});

const fakeWindow = new Proxy(window, {
  get,
  set,
});

const fn = new Function(
  'window',
  'context',
  `
    with(context){
        // code;
        'Vue' in window;
    }`,
);
fn(fakeWindow, context);
```

- this 导致的逃逸

```javascript
this.$CONFIG = { a: true }; // 由于this的特殊性，会被写到window上，严格模式下报错
if ($CONFIG.a) {
  // Uncaught ReferenceError: $CONFIG is not defined
  console.log(1);
}
```

`webpack` 的 `output.globalObject = window` 会自动隐式指向 `window` 的 `this` 构建会指向 `window`，需要注意的是在 `webpack` 低版本中可能不支持该配置。

#### DOM 隔离

`DOM` 隔离分为两种类型：样式节点、`dom` 节点。

- 快照沙箱：处理了样式节点未处理 `DOM` 节点
- VM 沙箱：会处理样式节点和 `DOM` 节点，并且提供了严格模式和非严格模式

样式的隔离在微前端里也是非常重要的一个点，在两个版本的快照里，采用不太一样的处理方式

> 快照沙箱的样式隔离

快照沙箱对样式的隔离主要是遍历 `HTML` 里的 `head` 标签，在 `activate` 的时候，把 `head` 里的 `dom` 记录下来，再 `deactivate` 的时候再恢复。

> VM 沙箱的 DOM 隔离

首先了解一个背景，`webpack` 在构建的时候，最终是通过 `appendChild` 去添加节点到 `html` 里的，所以我们只要通过劫持 `appendChild` 就可以知道有哪些节点被插入，从而实现插入节点的收集，方便进行移除。

在探索新的节点收集方案时，为了能够支持多实例，尝试了比较多的方案。

1. 劫持原型的 appendChild
   最初的版本我们通过重写 HTMLElement.prototype.appendChild，把 append 到 body 的样式放到子应用渲染的根节点里。由于劫持的是原型，这个方案无法支持多实例，如果有多个子应用同时运行，没办法区分是由哪个子应用添加的。

2. 劫持实例的 appendChild
   所以我们想到的是去劫持所有的 dom 节点，通过重写获取 dom 节点的方法，如 `document.querySelector`、`document.getElementByID`, 把返回的 `dom` 节点通过 `proxy` 进行包装，这样就能劫持 dom 实例的 appendChild，就可以区分是来自于哪个子应用。但是这个方案经过实践，出现的两个比较棘手的问题：

- 封装后的 dom 节点在传参的时候会报错，如

```javascript
var observer = new MutationObserver(() => {});
observer.observe(proxyDom); // Uncaught TypeError: Failed to execute 'observe' on 'MutationObserver': parameter 1 is not of type 'Node'.
```

- 递归的进行 proxy 带来了性能问题

3. 【目前方案】劫持原型的 `appendChild`，提供 `proxy` 版本的 `document`，在执行 `document.createElement` 方法时会为创建的节点打上来源的标签，表明是哪个应用创建了这个节点， 在通过 `appendChild` 等原型将节点添加文档流时，对节点进行收集，在应用销毁后将收集的节点也进行销毁，由于 `JavaScript` 语法的动态性和灵活性，目前的沙箱方案也存在一些漏洞：

- 节点通过 `parentNode` 一直向上查找至 `document` 节点

```javascript
function getDocuemnt() {
  let dom = document.querySelector('#wrapper');
  while (dom.parentNode) {
    dom = dom.parentNode;
  }
  console.log(dom === document);
}
```

比较多的组件库中都存在这一类逻辑，从而导致逻辑异常。目前的解决逻辑是，一旦子应用内有通过 `document` 进行了查询或创建的行为则将 `html` 的 parentNode 置为 `proxyDocument`

```javascript
function microTaskHtmlProxyDocument(proxyDocument) {
  const html = document.children[0];
  if (html && html.parentNode !== proxyDocument) {
    Object.defineProperty(html, 'parentNode', {
      value: proxyDocument,
      configurable: true,
    });

    if (setting) {
      setting = false;
      nextTick(() => {
        setting = true;
        Object.defineProperty(html, 'parentNode', {
          value: document,
          configurable: true,
        });
      });
    }
  }
}
```

##### 样式隔离

在 `DOM` 隔离章节，我们分别探索了快照沙箱和 `VM` 沙箱的实现，通过 `VM` 沙箱的隔离机制我们能够有效的收集应用创建的 `DOM` 副作用，并能够有效的区分副作用的来源。

目前 `VM` 沙箱的能力上我们能够清除应用在运行期间创建的 `DOM` 和样式节点，避免应用卸载后样式和节点影响其他应用运行，但由于样式会直接对在相同文档流上的节点生效，因此在多实例场景下，样式可能会影响其他应用的正常运行，并且子应用的样式可能会影响主应用或受到主应用样式的影响，因此样式的隔离是不得不考虑解决的副作用之一。

> CSS Module & CSS Namespace

通过修改基础组件样式前缀来实现框架和微应用依赖基础组件样式的隔离性（依赖于工程上 `CSS` 的预处理器编译和运行时基础组件库配置），同时避免全局样式的书写（依赖于约定或工程 `lint` 手段）。如果采用 `namespace` 可能需要在编译阶段做处理

- 优点
  - 不容易产生副作用，可以多实例共存
  - 对于同一个库不同版本的 `CSS`（如 `antd3` 和 `antd4`）, 可以做到彻底隔离
  - 子应用独立运行和在主应用运行表现一致
- 缺点
  - 子应用的节点会受到主应用的影响
  - 一定程度上依赖子应用的开发和构建配置
  - 无法处理 `HTML` 中通过 `link` 插入的样式
  - 未经过编译的动态创建样式也无法处理

> CSS Scope

类似于 `CSS Module` 或 `CSS Namespace`，通过 `scope` 来隔离子应用的所有样式。由于子应用有名称作为唯一标示，且挂载的容器在子应用切换时可以保证唯一性，可以通过统一加 `scope` 的形式处理所有的子应用样式。分为编译时和运行时两种处理方案：编译时提供 `webpack` 插件，对 `css` 编译时自动给子应用的样式添加 `scope`；运行时则是加载子应用时解析，由 `loader` 负责处理。

```css
// 宿主 host app
.next-btn {
  color: #eee;
}
body {
    color: red;
}

// 子应用 sub app
.garfish-module-a-wrapper .next-btn {
  color: #eee;
}

//宿主中生成的节点
<div class="garfish-module-a-wrapper">
  <!-- 子应用的节点 -->
</div>
```

- 优点
  - 不需要用户手动增加配置
- 缺点
  - 子应用的节点会受到主应用的影响
  - 子应用独立运行表现和在主应用运行表现可能不一致
  - 需要配合节点的处理一起进行（组件库可能会创建弹窗到 `body` 下，需要将节点劫持添加到容器内）

多实例下的样式隔离
在多实例场景下，可能会存在多份不同版本的 UI 组件库，从而导致样式冲突，目前的一种解决方案是通过构建工具给所有的样式都加上 namespace，如

```css
#garfish_app1 {
  ...css;
}
```

由于挂载的时候会把所有的节点都挂载在#garfish_app1 上，所以样式仍然能够生效。

```html
<div id="garfish_app1">
  <!-- 子应用的实际dom -->
</div>
```

> Shadow DOM

基于 `Web Components` 的 `Shadow DOM` 能力，将每个子应用包裹到一个 `Shadow DOM` 中，保证其运行时的样式的绝对隔离 `WebComponents Polyfill`

`Shadow dom` 是实现 `Web Components` 的主要技术之一，另外两项分别为 `custom element`、`HTML templates`，在 `Shadow dom` 用简单概括为：将 `Dom` 文档树中的某个节点变为隔离节点，隔离节点内的子节点样式、行为将与外界隔离（隔离节点内的样式不会受到外部影响，也不会影响外部节点，在隔离节点内的事件最终都只会冒泡到隔离节点中）

- Garfish 基于 ShadowDom 实现样式隔离

  - 将容器节点变为 shadow dom
  - 子应用节点操作转发到容器内，动态增加的样式和节点都会放置容器内
  - 查询节点操作转发到容器内
  - 事件向上传播，避免 `React` 依赖事件委托的库失效

- 优点
  - 浏览器基本的样式隔离
  - 支持主子应用样式隔离
  - 支持多实例
- 缺点
  - 需要同时处理 DOM，将 DOM 放置容器内
  - 可能会导致部分组件库或基础库无法正常运行（不支持放置 ShadowDom 内）

### 其他副作用

上面描述的其实只是对于变量的隔离，其实除了变量之外，还会有其他的副作用是需要隔离的，包括但不限于：

- 计时器：`setInterval`、`setTimeout`
- 全局事件监听：`addEventListener`
- 全局存储：`localStorage`、`sessionStorage`

解决方法主要分为两类，能够通过劫持收集的：

1. 如 `setInterval`、`setTimeout`、`addEventListener`，通过重写这些方法，在调用的时候记录起来，放进一个队列里，在沙箱销毁的时候统一进行清除。

2. 持久化数据，无法通过劫持进行收集的，使用命名空间来区分
   如 `localStorage`，`sessionStorage`，重写对象和方法

```javascript
// 代码
localStorage.setItem('a', '1');

// 在SandboxA里执行实际效果
localStorage.setItem('Garfish_A_a', '1');

// 逃逸的场景
Garfish.getRawLocalStorage().setItem('a', '1');
```

## 两种沙箱的对比

![image](https://user-images.githubusercontent.com/27547179/164144636-2d85409e-d011-43c8-929b-07eb287abf2f.png)
![image](https://user-images.githubusercontent.com/27547179/164144650-c2d26150-7779-4bb0-bfbb-3404615335b9.png)
![image](https://user-images.githubusercontent.com/27547179/164144658-3997cb63-20f2-4f8c-a4b4-199389d7f5be.png)



---
url: /guide/advance/plugins.md
---

# 插件指南

import Highlight from '@components/Highlight';
import BeforeLoad from '@components/lifeCycle/\_beforeLoad.mdx';
import AfterLoad from '@components/lifeCycle/\_afterLoad.mdx';
import ErrorLoadApp from '@components/lifeCycle/\_errorLoadApp.mdx';
import BeforeEval from '@components/lifeCycle/\_beforeEval.mdx';
import AfterEval from '@components/lifeCycle/\_afterEval.mdx';
import BeforeMount from '@components/lifeCycle/\_beforeMount.mdx';
import AfterMount from '@components/lifeCycle/\_afterMount.mdx';
import ErrorMountApp from '@components/lifeCycle/\_errorMountApp.mdx';
import BeforeUnmount from '@components/lifeCycle/\_beforeUnmount.mdx';
import AfterUnmount from '@components/lifeCycle/\_afterUnmount.mdx';
import ErrorUnmountApp from '@components/lifeCycle/\_errorUnmountApp.mdx';
import OnNotMatchRouter from '@components/lifeCycle/\_onNotMatchRouter.mdx';

Garfish 框架引入了插件化机制，目的是为了让开发者能够通过编写插件的方式来扩展更多功能，或为自身业务定制个性化功能；同时框架的基础能力也都是通过插件机制来实现，确保框架核心足够精简和稳定。

## 插件能做什么

插件的功能范围没有严格的限制，一般有下面两种：

1. 添加全局方法或增加默认参数
2. 在应用的生命周期中自定义功能（例如：`Garfish router`、`Garfish sandbox`）

## 编写插件

`Garfish Router` 增加了全局方法和应用的自动渲染和销毁能力，下面让我们来以 `Garfish router` 为例，如何编写一个插件，来实现路由的能力。

当插件被注册到 `Garfish` 框架时，将会调用插件函数并将 `GarfishInstance` 作为参数传递，函数的返回值中包括插件的基本信息：`name`、`version`，除了基本信息外最重要的则是包括 `hook`，`Garfish` 框架将在应用的整个生命周期中触发 `hook` 的调用，可以在 `hook` 中对信息进行二次处理或执行特定的功能。

让我们从编写插件函数开始，建议在单独的文件中创建它并将其导出，如下所示，以保持插件逻辑的整洁和分离，在实际开发过程中我们建议将实际插件的内容放置一个函数中返回，以便插件在实际调用时可接收参数

```ts
// plugins/router.ts
import type { interfaces } from 'garfish';
// function return plugin
export function GarfishRouter(_args?: any) {
  // Plugin code goes here
  return function (GarfishInstance: interfaces.Garfish): interfaces.Plugin {
    return {
      name: 'garfish-router',
      version: '1.2.1',
      // ...
    };
  };
}
```

`Garfish Router` 的这个 `plugin` 期望达到的目标是通过提供的 `Router Map` 后 `Garfish` 框架能够自动的完成微前端应用的渲染和销毁调度，从而降低典型中台中管理应用销毁和渲染的工作，提升开发效率。那么要实现这个需求我们需要依次实现以下功能：

- 扩展类型
  - `appInfo` 的类型，让 `appInfo` 类型提示支持 `activeWhen`、`basename` 等配置
  - `Garfish` 增加 `router` 类型
- 为 `Garfish` 实例扩展 `router` 方法，用于实现路由跳转和路由监听等能力
- 监听 `bootstrap hook`（该 hook 会在主应用触发 `Garfish.run` 后调用），触发 `bootstrap` 后
  - 劫持路由变化：改写 `history.push`、`history.replace`，监听 `popstate` 浏览器后退事件
  - 当路由发生变化时通过 `appInfo` 的 `activeWhen` 进行规则判断，对应用进行渲染和销毁
- 监听 `registerApp hook`（该 hook 会在注册子应用时触发）
  - 当有新注册应用时对新应用进行检验是否如何渲染条件，进行销毁

:::tip
Garfish Router 就是通过 Garfish 的 Plugin 机制实现，以下案例精简了大部分逻辑，主要介绍如何编写插件来扩展 Garfish 的整体功能，若想了解实现，请参考 [`Garfish Router plugin`](https://github.com/modern-js-dev/garfish/blob/260143bb70ca81c64069650ae278088a2ca8a62f/packages/router/src/index.ts)
:::

```ts
import type { interfaces } from 'garfish';
declare module 'garfish' {
  // 为 GarfishInstance 添加 router 方法
  export default interface Garfish {
    router: {
      push: (info: {
        path: string;
        query?: { [key: string]: string };
        basename?: string;
      }) => void;
      replace: (info: {
        path: string;
        query?: { [key: string]: string };
        basename?: string;
      }) => void;
    };
  }

  export namespace interfaces {
    // 为全局配置增加 autoRefreshApp、onNotMatchRouter 参数类型
    export interface Config {
      onNotMatchRouter?: (path: string) => Promise<void> | void;
    }

    export interface AppInfo {
      // 手动加载，可不填写路由
      activeWhen?: string | ((path: string) => boolean);
      basename?: string;
    }
  }
}

// 这里仅做伪代码的演示，功能无法正常运行
export function GarfishRouter(_args?: { autoRefreshApp?: boolean }) {
  return function (Garfish: interfaces.Garfish): interfaces.Plugin {
    // 为 Garfish 实例添加 router 方法
    Garfish.router = {
      push: ({ path }) => history.push(null, '', path),
      replace: ({ path }) => history.replace(null, '', path),
    };

    return {
      name: 'router',
      version: '1.0.0',
      // 在触发 Garfish.run 后启动路由监听，自动渲染和销毁应用
      bootstrap(options: interfaces.Options) {
        let activeApp = null;
        const unmounts: Record<string, Function> = {};
        const { basename } = options;

        const apps = Object.values(Garfish.appInfos);

        // 该函数会劫持 history 变化，当某个 appInfo 的 activeWhen 符合触发条件后会触发 active 回调
        // 提供 appInfo 信息，这个时候通过 Garfish.loadApp 加载该应用并进行销毁
        // 当某个 appInfo 处于已经渲染状态，并且在路由发生变化后处于销毁状态将会触发 deactive 回调
        // 通过 appInfo，触发缓存的 app 实例的销毁函数
        listenRouterAndReDirect({
          basename,
          active: async (appInfo: interfaces.AppInfo, rootPath: string) => {
            const { name, cache = true, active } = appInfo;

            // 当前应用处于激活状态后触发
            const app = await Garfish.loadApp(appInfo.name, {
              basename: rootPath,
              entry: appInfo.entry,
              cache: true,
              domGetter: appInfo.domGetter,
            });

            if (app) {
              const isDes = cache && app.mounted;
              isDes ? await app.show() : await app.mount();

              unmounts[name] = () => {
                const isDes = cache && app.mounted;
                isDes ? await app.show() : await app.mount();
              };
            }
          },
          deactive: async (appInfo: interfaces.AppInfo, rootPath: string) => {
            const { name, deactive } = appInfo;
            const unmount = unmounts[name];
            unmount && unmount();
          },
          autoRefreshApp,
          notMatch: onNotMatchRouter,
          apps,
          listening: true,
        });
      },

      registerApp(appInfos) {
        // 将新注册的应用信息注入到路由中
        const appList = Object.values(appInfos);
        router.registerRouter(appList.filter((app) => !!app.activeWhen));
        // 触发路由的重定向，检测当前应用是否需要触发渲染
        initRedirect();
      },
    };
  };
}
```

> 插件编写总结

- 若要为 `Garfish` 实例扩展方法，通过 `declare module` 直接扩展 `Garfish` 的 `interfaces`，然后通过插件函数获取 `Garfish` 的实例直接添加方法，用于扩展 `Garfish` 的能力
- 可通过 `namespace interfaces` 直接扩展 `Garfish config` 和 `AppInfo` 配置
- 在对应用用的生命周期中进行能力的扩展

## 插件公约

- 插件应该包括清晰的名称
- 如果插件单独封装至 `npm` 包，在 `package.json` 中添加 `garfish-plugin` 关键词
- 插件应该包括完备的测试
- 插件应该具备完整的使用文档
- 如果你觉得你的插件足够通用，请联系：zhouxiao.shaw@bytedance.com，评估后是否是和加入推荐列表

## 使用插件

通过调用 `Garfish.usePlugin` 方法将插件添加到你的应用程序中。

我们将使用在 [`如何编写插件`](#如何编写插件) 部分中创建的 `routerPlugin` 插件进行演示。

`usePlugin()` 方法第一个参数接收要安装的插件，在这种情况下为 `routerPlugin` 的返回值。

它还会自动阻止你多次使用同一插件，因此在同一插件上多次调用只会安装一次该插件，`Garfish` 内部通过插件执行后返回的 `name` 作为唯一标识来进行区分，在进行插件命名时，请确保不会和其他插件之间发生冲突。

```ts
import Garfish from 'garfish';
import routerPlugin from './plugins/router';

Garfish.usePlugin(routerPlugin());
```

## `usePlugin`

通过 `Garfish.usePlugin` 可以注册插件

```ts
Garfish.usePlugin(plugin: (GarfishInstance: interfaces.Garfish)=> interfaces.Plugin)
```

## `plugin`

### `name`

- Type: `string`
- 插件的名称，作为插件的唯一标识和便于调试

### `version?`

- Type: `string`
- 插件的版本号，用于观测线上环境使用使用的插件版本

### `beforeBootstrap?`

- Type: `(options: interfaces.Options) => void`
  - 该 `hook` 的第一个参数为 `Garfish.run` 提供的配置信息
- Kind: `sync`, `sequential`
- Trigger:
  - 在 [`Garfish.run`](/api/run) 调用后触发
  - 触发该 `hook` 时配置未注册到全局

### `bootstrap?`

- Type: `(options: interfaces.Options) => void`
  - 该 `hook` 的第一个参数为 `Garfish.run` 提供的配置信息
- Kind: `sync`, `sequential`
- Trigger:
  - 在 [`Garfish.run`](/api/run) 调用后触发
  - 触发该 `hook` 时配置已经注册到全局
- Previous Hook: `beforeBootstrap`

### `beforeRegisterApp?`

- Type: `(appInfo: interfaces.AppInfo | Array<interfaces.AppInfo>) => void`
  - 该 `hook` 的第一个参数为需要注册的应用信息
- Kind: `sync`, `sequential`
- Trigger:
  - 调用 [`Garfish.run`](/api/run) 且，提供了 `apps` 参数时触发
  - 直接通过 [`Garfish.registerApp`](/api/registerApp) 调用时
  - 触发该 `hook` 是子应用信息尚未注册成功

### `registerApp?`

- Type: `(appInfo: interfaces.AppInfo | Array<interfaces.AppInfo>) => void`
  - 该 `hook` 的第一个参数为需要注册的应用信息
- Kind: `sync`, `sequential`
- Trigger:
  - 调用 [`Garfish.run`](/api/run) 且，提供了 `apps` 参数时触发
  - 直接通过 [`Garfish.registerApp`](/api/registerApp) 调用时
  - 触发该 `hook` 是子应用信息注册成功

### beforeLoad



import Highlight from '@components/Highlight';

- Type: <Highlight> async (appInfo: AppInfo, appInstance: App) => false | undefined </Highlight>
  - 该 `hook` 的参数分别为：应用信息、应用实例；
  - 当返回 `false` 时将中断子应用的加载及后续流程；
- Kind: `async`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 时触发该 `hook`
  - 子应用加载前触发，此时还未开始加载子应用资源；

- 示例

```ts
Garfish.run({
  ...,
  beforeLoad(appInfo) {
    console.log('子应用开始加载', appInfo.name);
  }
```


### afterLoad



import Highlight from '@components/Highlight';

- Type: <Highlight> async (appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- 该 `hook` 的参数分别为：应用信息、应用实例；
- Kind: `async`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 后并且子应用加载完成时触发该 `hook`；

- 示例

```ts
Garfish.run({
  ...,
  afterLoad(appInfo) {
    console.log('子应用加载完成', appInfo.name);
  }
})
```


### errorLoadApp



import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
  - 该 `hook` 的参数分别为：`error` 实例、 `appInfo` 信息、`appInstance` 应用实例
  - 一旦设置该 hook，子应用加载错误不会 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 过程中，并且加载失败时触发该 `hook`

- 示例

```ts
Garfish.run({
  ...,
  errorLoadApp(error, appInfo) {
    console.log('子应用加载异常', appInfo.name);
    console.error(error);
  }
})
```


### beforeMount



import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, appInstance: interfaces.App, cacheMode: boolean) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`appInstance` 应用实例、是否为 `缓存模式` 渲染和销毁
- Kind: `sync`, `sequential`
- Previous Hook: `beforeEval`、`afterEval`
- Trigger:

  - 此时子应用资源准备完成，运行时环境初始化完成，准备开始渲染子应用 DOM 树；
  - 在调用 `app.mount` 或 `app.show` 触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发
    - 在使用 `app.mount` 渲染应用是 `cacheMode` 为 `false`；
    - 在使用 `app.show` 渲染应用是 `cacheMode` 为 `true`；

- 示例

```ts
Garfish.run({
  ...,
  beforeMount(appInfo) {
    console.log('子应用开始渲染', appInfo.name);
  }
})
```


### afterMount



import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, appInstance: interfaces.App, cacheMode: boolean) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`appInstance` 应用实例、是否为 `缓存模式` 渲染和销毁
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`
- Trigger:

  - 此时子应用 DOM 树已渲染完成，garfish 实例 `activeApps` 中已添加当前子应用 app 实例；
  - 在挂载过程中，会调用应用生命周期中的 [`render` 函数](/guide/start#2导出-provider-函数)，用户可在挂载前定义相关操作；
  - 若挂载过程中出现异常，会触发 [errorMountApp](/api/run#errormountapp)，同时会清除已创建的 app 渲染容器 appContainer

- 示例

```ts
Garfish.run({
  ...,
  afterMount(appInfo) {
    console.log('子应用渲染结束', appInfo.name);
  }
})
```


### beforeEval



import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, code: string, env: `Record<string, any>`, url: string, options) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`code` 执行的代码、`env` 要注入的环境变量，`url` 代码的资源地址、`options` 参数选项（例如 `async` 是否异步执行、`noEntry` 是否是 `noEntry` 模式）；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeMount`
- Trigger:

  - 在子应用挂载过程中、实际执行代码前触发该 hook；
  - 应用 html 内的 script 和动态创建的脚本执行时都会触发该 hook
  - 此时 DOM 树已添加至文档流中，子应用代码准备执行；
  - 若代码执行过程中抛出异常，则将触发 [errorMountApp](/api/run#errormountapp)，否则触发 [beforeEval](/api/run#afterEval)

- 示例

```ts
Garfish.run({
  ...,
  beforeEval(appInfo) {
    console.log('子应用代码开始执行', appInfo.name);
  }
})
```


### afterEval



import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, code: string, env: `Record<string, any>`, url: string, options) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`code` 执行的代码、`env` 要注入的环境变量，`url` 应用访问地址、`options` 参数选项例如 `async` 是否异步执行、`noEntry` 是否是 `noEntry` 模式；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`
- Trigger:

  - 在实际执行代码后。`afterMount` 触发前触发；
  - 子应用 html 内的 script 和动态创建的脚本执行时都会触发该 hook

- 示例

```ts
Garfish.run({
  ...,
  afterEval(appInfo) {
    console.log('子应用代码执行完成', appInfo.name);
  }
})
```


### errorMountApp



import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
  - 一旦设置该 hook，子应用加载错误不会 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`、`afterMount`
- Trigger:

  - 在渲染过程中出现异常会触发该 `hook`，子应用同步执行的代码出现异常会触发该 `hook`，异步代码无法触发

- 示例

```ts
Garfish.run({
  ...,
  errorMountApp(error, appInfo) {
    console.log('子应用渲染异常', appInfo.name);
    console.error(error);
  }
})
```


### beforeUnmount



import Highlight from '@components/Highlight';

- Type: <Highlight> ( appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`、`afterMount`
- Trigger:
  - 在调用 `app.unmount` 或 `app.hide` 触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发
    - 在使用 `app.unmount` 渲染应用是 `cacheMode` 为 `false`；
    - 在使用 `app.hide` 渲染应用是 `cacheMode` 为 `true`；
  - 此时子应用 DOM 元素还未卸载，副作用尚未清除；
  - 此时子应用 DOM 树已渲染完成，garfish 实例 `activeApps` 中已添加当前子应用 app 实例；


### afterUnmount



import Highlight from '@components/Highlight';

- Type: <Highlight> ( appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- Kind: `sync`, `sequential`
- Trigger:
  - 此时，应用在渲和运行过程中产生的副作用已清除，DOM 已卸载，沙箱副作用已清除，garfish 实例 `activeApps` 当前 app 已移除；
  - 在应用销毁过程中会调用应用生命周期中的 [`destory` 函数](/guide/start#2导出-provider-函数)，用户可在销毁前定义相关操作；
  - 若应用卸载过程中出现异常，会触发 [errorUnmountApp](/api/run#errorUnmountApp)


### errorUnmountApp



import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App)=> void </Highlight>
  - 一旦设置该 hook，子应用销毁错误不会向上 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Trigger:

  - 在 `app.unmount` 或 `app.hide` 销毁过程中出现异常则会触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发

- 示例

```ts
Garfish.run({
  ...,
  errorUnmountApp(error, appInfo) {
    console.log('子应用销毁异常', appInfo.name);
    console.error(error);
  }
})
```


### onNotMatchRouter



import Highlight from '@components/Highlight';

- Type: <Highlight> (path: string)=> void </Highlight>
  - 该 `hook` 的参数分别为：应用信息、应用实例；
- Kind: `sync`, `sequential`
- Trigger:

  - 路由发生变化当前未激活子应用且未匹配到任何子应用时触发

- 示例

```ts
Garfish.run({
  ...,
  onNotMatchRouter(path) {
    console.log('未匹配到子应用', path);
  }
})
```




---
url: /api/__meta__.md
---




---
url: /api/index.md
---

# 概览

```ts
import Garfish from "garfish";
```
在主应用中，我们通过 `import Garfish from "garfish";` 来引入 Garfish，并调用相关 Garfish api 去注册子应用或运行微前端应用。

其中，Garfish 是 `garfish` 包默认导出的实例，实例上包含微前端相关API，用户可以通过相应 API 完成对整个微前端应用的管理。


:::tip
这里需要特殊说明的是，子应用不需要额外引入 Garfish 实例，子应用可通过 `window.Garfish` 获取全局 Garfish 实例信息，参考 [Garfish 环境变量](../guide/quickStart/env.md)。


:::


## Garfish 实例方法
- [Garfish.run](/api/run) （用于初始化应用参数、启动路由监听，当路由发生变化时自动激活应用或销毁应用）
- [Garfish.registerApp](/api/registerApp)（用于动态注册应用信息）
- [Garfish.loadApp](/api/loadApp)（可以手动控制子应用加载和销毁）
- [Garfish.router](/api/router)（提供路由跳转和路由守卫能力）
- [Garfish.channel](/api/channel)（提供应用间通信的能力）
- [Garfish.setExternal](/api/setExternal)（支持应用间的依赖共享）
- [Garfish.getGlobalObject](/api/getGlobal)（用于获取真实 Window）
- [Garfish.setGlobalObject](/api/setGlobal)（用于设置真实 Window 的值）
- [Garfish.clearEscapeEffect](/api/clearEscapeEffect)（用于清除逃逸的副作用）



---
url: /api/run.md
---

# Garfish.run
import Highlight from '@components/Highlight';



















用于初始化全局配置、注册子应用信息，并启动基于路由匹配的子应用自动渲染流程。

> garfish 基于 `activeWhen` 参数自动进行子应用激活匹配，可参考 [activeWhen](/api/registerApp#activewhen) 了解 garfish 路由匹配逻辑；


## 类型

```ts
run(options?: interfaces.Options): Garfish;
```

```ts
// type 定义
export interface Options extends Config, AppGlobalConfig, GlobalLifecycle {}
```

## 默认值

- `{}`

## 示例

```ts
import Garfish from "garfish";
import type { interfaces } from "garfish";

const config: interfaces.Options = {
    /* global options */
    basename: '/',
    domGetter: '#subApp',
    disablePreloadApp: false,
    ...
    /* app infos */
    apps: [
      {
        name: 'react',
        activeWhen: '/react',
        entry: 'http://localhost:3000',
        ...
      }
    ],
    /* lifecycle hooks */
    beforeLoad(appInfo) {
      console.log('子应用开始加载', appInfo.name);
    },
    afterLoad(appInfo) {
      console.log('子应用加载完成', appInfo.name);
    },
    ...
}
Garfish.run({ config });
```

## 参数

`options`

### domGetter?



import Highlight from '@components/Highlight';

- Type: <Highlight>interfaces.DomGetter</Highlight>

```ts
export type DomGetter =
  | string
  | (() => Element | null)
  | (() => Promise<Element>);
```

- 子应用的默认挂载点，可选，没有默认值，若省略需要在子应用 AppInfo 中单独指定。二者同时存在时，子应用指定优先级更高；
- 当提供 `string` 类型时需要其值是 `selector`, Garfish 内部会使用 `document.querySelector(domGetter)` 去选中子应用的挂载点
- 当提供 `string` 类型的 `domGetter` 时，子应用在触发渲染后并不会若当前文档流上并不存在挂载点，`Garfish` 框架内部在 `3s` 内轮讯是否有挂载点
- 当提供函数时，将在子应用挂载过程中执行此函数，并期望返回一个 dom 元素；
- 若 `domGetter` 在子应用渲染时无法查询到挂载点，则会丢出 `domGetter` 无效的异常


### basename?


import Highlight from '@components/Highlight';

- Type: <Highlight> string </Highlight>
- 子应用的基础路径，可选，默认值为全局 [basename](/api/run#basename)；
- 通过路由驱动自动加载子应用时实际传递给子应用的 basename 为 `basename + activeWhen` 计算的值
- 若手动载入渲染应用时 `basename` 为实际传入的值
- 通过 [provider 函数](/guide/start#2导出-provider-函数) 的 `basename` 参数透传给子应用，子应用需要将 basename 设置为相应子应用的基础路由，这是必须的；
- [为什么子应用需要设置 basename ?](/issues#子应用拿到-basename-的作用)


### props?

- Type: <Highlight>Object</Highlight>
- 初始化时主应用传递给子应用的数据，可选。子应用 [`provider` 导出函数](/guide/quickStart/start.md#2导出-provider-函数) 生命周期方法中将接收到此数据；

### disablePreloadApp?

- Type: <Highlight> boolean </Highlight>
- 是否禁用子应用的资源预加载，可选，默认值为 `false`。默认情况下 Garfish 会开启子应用的资源预加载能力；
- Garfish 会在用户端计算子应用打开的次数，应用的打开次数越多，预加载权重越大；
- 预加载能力在弱网情况和手机端将不会开启；

### disableSourceListCollect?

- Type: <Highlight> boolean </Highlight>
- 是否禁用收集子应用资源列表，可选，默认值为 `false`。默认情况下 Garfish 会自动收集子应用的资源，用于进行监控分析；

### sandbox?



import Highlight from '@components/Highlight';

- Type: <Highlight> SandboxConfig | false </Highlight>可选，默认值为 [全局 sandbox 配置](/api/run#sandbox)，当设置为 false 时关闭沙箱；

- SandboxConfig：

```ts
interface SandboxConfig {
  // 是否开启快照沙箱，默认值为 false：关闭快照沙箱，开启 vm 沙箱
  snapshot?: boolean;
  // 是否自动以子应用入口的域名前缀对子应用 fetch 请求的进行补齐，默认值为 false
  fixBaseUrl?: boolean;
  // 是否自动以子应用入口的域名前缀对相对路径资源进行前缀修正，默认值为 true，v1.15.0 版本提供
  fixStaticResourceBaseUrl?: boolean;
  // 是否开启开启严格隔离，默认值为 false。开启严格隔离后，子应用的渲染节点将会开启 Shadow DOM close 模式，并且子应用的查询和添加行为仅会在 DOM 作用域内进行
  strictIsolation?: boolean;
  // modules 仅在 vm 沙箱时有效，用于覆盖子应用执行上下文的环境变量，使用自定义的执行上下文，默认值为[]
  modules?: Array<Module> | Record<string, Module>;
  // disableElementtiming 1.14.4 版本提供，默认值为 false，将会给子应用元素注入 elementtiming 属性，可以通过此属性获取子应用元素的加载时间
  disableElementtiming?: boolean;
  // fixOwnerDocument  1.17.2 版本提供 ，默认值 false，目前可能会存在 ownerDocument 逃逸的情况，设置为 true 之后将会避免 ownerDocument 逃逸
  fixOwnerDocument?: boolean;
  // disableLinkTransformToStyle  1.18.0 版本提供 ，默认值 false，禁用掉 link 自动 transform 成 style 的行为
  disableLinkTransformToStyle?: boolean;
  // excludeAssetFilter 1.18.0 版本提供，默认值为 undefined，用于过滤不需要再子应用沙箱中执行的资源例如 jsonp，url 参数为对应 script 的地址，返回 true 则会过滤掉该资源
  excludeAssetFilter?: (url: string) => boolean;
}

type Module = (sandbox: Sandbox) => OverridesData | void;

export interface OverridesData {
  recover?: (context: Sandbox['global']) => void;
  prepare?: () => void;
  created?: (context: Sandbox['global']) => void;
  override?: Record<PropertyKey, any>;
}
```

- 示例

```ts
Garfish.run({
  sandbox: {
    snapshot: false,
    strictIsolation: false,
    // 覆盖子应用 localStorage，使用当前主应用 localStorage
    modules: [
      () => ({
        override: {
          localStorage: window.localStorage,
        },
      }),
    ],
  },
});
```

:::danger
请注意：
如果你在沙箱内自定义的行为将会产生副作用，请确保在 recover 函数中清除你的副作用，garfish 将在应用卸载过程中执行 recover 函数销毁沙箱副作用，否则可能会造成内存泄漏。
:::

- 在什么情况下我应该关闭 sandbox ?

  > Garfish 目前已默认支持沙箱 esModule 能力，若需要在 vm 沙箱支持 esModule 应用，请使用 `@garfish/es-module` garfish 官方插件支持此能力，但这会带来严重的性能问题，[原因](/issues/#esmodule)。如果你的项目不是很需要在 vm 沙箱下运行，此时可以关闭沙箱；

- [Garfish 沙箱机制](/guide/sandbox)

:::info
若开启快照沙箱，请注意：

1. 快照沙箱无法隔离主、子应用
2. 快照沙箱无法支持多实例（同时加载多个子应用）

:::


### autoRefreshApp?

- Type: <Highlight> boolean </Highlight>
- 主应用在已经打开子应用页面的前提下，跳转子应用的子路由触发子应用的视图更新，默认值为 `true`；
- 若关闭 `autoRefreshApp`, 则跳转 <Highlight>  子应用子路由 </Highlight> 将只能通过 [Garfish.router](/api/router) 进行跳转，使用框架自身路由 API（如 react-router）跳转将失效；
- 在某些场景下，通过主应用触发子应用视图更新可能会导致触发子应用的视图刷新而触发子应用的 hook，所以提供关闭触发子应用视图刷新的能力；

### protectVariable?



import Highlight from '@components/Highlight';

- Type: <Highlight> string[] </Highlight>
- 在开启沙箱的情况下，提供使得 window 上的某些变量处于受保护状态的能力：这些值的读写不会受到沙箱隔离机制的影响，所有应用均可读取到，可选；
- 若希望在应用间共享 window 上的某些值，可将该值放置在数组中；
- 该属性与 [setGlobalValue](/api/setGlobalObject) 功能相同，推荐使用 `protectVariable` 属性，通过 `protectVariable` 可以明确的感知哪些值可能在应用间相互影响；


### insulationVariable?



import Highlight from '@components/Highlight';

- Type: <Highlight> string[] </Highlight>
- 在开启沙箱的情况下，沙箱的子应用的环境变量将会从主应用中继承，举例：
  - 在加载子应用前，主应用有一段：`window.xxxx = 123`
  - 子应用中可以获取获取主应用的环境变量 `console.log(window.xxxx)`，输出 123
  - 因为目前 `Garfish` 的主子应用环境是隔离的，但是子应用的环境继承至主应用时可能会造成一些影响不符合预期
- 若希望在子应用某些环境变量不继承至主应用，可以使用 `insulationVariable` 配置，例如：
  - `insulationVariable: ['xxxx']`
  - 'xxxx' 在子应用中将不会继承至主应用，`console.log(window.xxxx)` 输出 `undefined`


### apps?

- Type: <Highlight> AppInfo[] </Highlight>
- 子应用列表信息，此字段参数信息与 [registerApp](../api/registerApp.md) 一致，可跳转查看详细介绍；

```ts
export interface AppInfo extends AppConfig, AppLifecycle {}

export interface AppGlobalConfig {
  // 子应用的基础路径，通过路由驱动自动加载子应用时实际传递给子应用的 basename 为计算的值
  // 若手动载入渲染应用时 basename 为这里指定的值
  basename?: string;
  // 子应用挂载点，同上，此处会覆盖全局默认的 domGetter
  domGetter?: DomGetter;
  // 传递给子应用的数据, 同上，此处会覆盖全局默认的 props
  props?: Record<string, any>;
  // 子应用的沙箱配置，同上，此处会覆盖全局默认的 sandbox
  sandbox?: false | SandboxConfig;
}

export type AppConfig = Partial<AppGlobalConfig> & {
  // 子应用的名称，需要唯一
  name: string;
  // 子应用的入口资源地址，支持 HTML 和 JS
  entry?: string;
  // 是否缓存子应用，默认值为 true；
  cache?: boolean;
  // 是否检查 provider, 默认为true；
  noCheckProvider?: boolean;
};
```

- 示例

```ts
Garfish.run({
  ...,
  apps: [
    {
      name: 'vue-app',
      basename: '/demo',
      activeWhen: '/vue-app',
      entry: 'http://localhost:3000',
      props: {
        msg: 'vue-app msg',
      }
    }
  }
]
```

### beforeLoad


import Highlight from '@components/Highlight';

- Type: <Highlight> async (appInfo: AppInfo, appInstance: App) => false | undefined </Highlight>
  - 该 `hook` 的参数分别为：应用信息、应用实例；
  - 当返回 `false` 时将中断子应用的加载及后续流程；
- Kind: `async`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 时触发该 `hook`
  - 子应用加载前触发，此时还未开始加载子应用资源；

- 示例

```ts
Garfish.run({
  ...,
  beforeLoad(appInfo) {
    console.log('子应用开始加载', appInfo.name);
  }
```


### afterLoad


import Highlight from '@components/Highlight';

- Type: <Highlight> async (appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- 该 `hook` 的参数分别为：应用信息、应用实例；
- Kind: `async`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 后并且子应用加载完成时触发该 `hook`；

- 示例

```ts
Garfish.run({
  ...,
  afterLoad(appInfo) {
    console.log('子应用加载完成', appInfo.name);
  }
})
```


### errorLoadApp


import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
  - 该 `hook` 的参数分别为：`error` 实例、 `appInfo` 信息、`appInstance` 应用实例
  - 一旦设置该 hook，子应用加载错误不会 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Trigger:

  - 在调用 `Garfish.load` 过程中，并且加载失败时触发该 `hook`

- 示例

```ts
Garfish.run({
  ...,
  errorLoadApp(error, appInfo) {
    console.log('子应用加载异常', appInfo.name);
    console.error(error);
  }
})
```


### beforeMount


import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, appInstance: interfaces.App, cacheMode: boolean) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`appInstance` 应用实例、是否为 `缓存模式` 渲染和销毁
- Kind: `sync`, `sequential`
- Previous Hook: `beforeEval`、`afterEval`
- Trigger:

  - 此时子应用资源准备完成，运行时环境初始化完成，准备开始渲染子应用 DOM 树；
  - 在调用 `app.mount` 或 `app.show` 触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发
    - 在使用 `app.mount` 渲染应用是 `cacheMode` 为 `false`；
    - 在使用 `app.show` 渲染应用是 `cacheMode` 为 `true`；

- 示例

```ts
Garfish.run({
  ...,
  beforeMount(appInfo) {
    console.log('子应用开始渲染', appInfo.name);
  }
})
```


### afterMount


import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, appInstance: interfaces.App, cacheMode: boolean) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`appInstance` 应用实例、是否为 `缓存模式` 渲染和销毁
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`
- Trigger:

  - 此时子应用 DOM 树已渲染完成，garfish 实例 `activeApps` 中已添加当前子应用 app 实例；
  - 在挂载过程中，会调用应用生命周期中的 [`render` 函数](/guide/start#2导出-provider-函数)，用户可在挂载前定义相关操作；
  - 若挂载过程中出现异常，会触发 [errorMountApp](/api/run#errormountapp)，同时会清除已创建的 app 渲染容器 appContainer

- 示例

```ts
Garfish.run({
  ...,
  afterMount(appInfo) {
    console.log('子应用渲染结束', appInfo.name);
  }
})
```


### beforeEval


import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, code: string, env: `Record<string, any>`, url: string, options) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`code` 执行的代码、`env` 要注入的环境变量，`url` 代码的资源地址、`options` 参数选项（例如 `async` 是否异步执行、`noEntry` 是否是 `noEntry` 模式）；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeMount`
- Trigger:

  - 在子应用挂载过程中、实际执行代码前触发该 hook；
  - 应用 html 内的 script 和动态创建的脚本执行时都会触发该 hook
  - 此时 DOM 树已添加至文档流中，子应用代码准备执行；
  - 若代码执行过程中抛出异常，则将触发 [errorMountApp](/api/run#errormountapp)，否则触发 [beforeEval](/api/run#afterEval)

- 示例

```ts
Garfish.run({
  ...,
  beforeEval(appInfo) {
    console.log('子应用代码开始执行', appInfo.name);
  }
})
```


### afterEval


import Highlight from '@components/Highlight';

- Type: <Highlight> (appInfo: AppInfo, code: string, env: `Record<string, any>`, url: string, options) => void </Highlight>
  - 该 `hook` 的参数分别为：`appInfo` 信息、`code` 执行的代码、`env` 要注入的环境变量，`url` 应用访问地址、`options` 参数选项例如 `async` 是否异步执行、`noEntry` 是否是 `noEntry` 模式；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`
- Trigger:

  - 在实际执行代码后。`afterMount` 触发前触发；
  - 子应用 html 内的 script 和动态创建的脚本执行时都会触发该 hook

- 示例

```ts
Garfish.run({
  ...,
  afterEval(appInfo) {
    console.log('子应用代码执行完成', appInfo.name);
  }
})
```


### errorMountApp


import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
  - 一旦设置该 hook，子应用加载错误不会 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`、`afterMount`
- Trigger:

  - 在渲染过程中出现异常会触发该 `hook`，子应用同步执行的代码出现异常会触发该 `hook`，异步代码无法触发

- 示例

```ts
Garfish.run({
  ...,
  errorMountApp(error, appInfo) {
    console.log('子应用渲染异常', appInfo.name);
    console.error(error);
  }
})
```


### beforeUnmount


import Highlight from '@components/Highlight';

- Type: <Highlight> ( appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- Kind: `sync`, `sequential`
- Previous Hook: `beforeLoad`、`afterLoad`、`beforeMount`、`afterMount`
- Trigger:
  - 在调用 `app.unmount` 或 `app.hide` 触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发
    - 在使用 `app.unmount` 渲染应用是 `cacheMode` 为 `false`；
    - 在使用 `app.hide` 渲染应用是 `cacheMode` 为 `true`；
  - 此时子应用 DOM 元素还未卸载，副作用尚未清除；
  - 此时子应用 DOM 树已渲染完成，garfish 实例 `activeApps` 中已添加当前子应用 app 实例；


### afterUnmount


import Highlight from '@components/Highlight';

- Type: <Highlight> ( appInfo: AppInfo, appInstance: interfaces.App) => void </Highlight>
- Kind: `sync`, `sequential`
- Trigger:
  - 此时，应用在渲和运行过程中产生的副作用已清除，DOM 已卸载，沙箱副作用已清除，garfish 实例 `activeApps` 当前 app 已移除；
  - 在应用销毁过程中会调用应用生命周期中的 [`destory` 函数](/guide/start#2导出-provider-函数)，用户可在销毁前定义相关操作；
  - 若应用卸载过程中出现异常，会触发 [errorUnmountApp](/api/run#errorUnmountApp)


### errorUnmountApp


import Highlight from '@components/Highlight';

- Type: <Highlight> (error: Error, appInfo: AppInfo, appInstance: interfaces.App)=> void </Highlight>
  - 一旦设置该 hook，子应用销毁错误不会向上 throw 到文档流中，全局错误监听将无法捕获到；
- Kind: `sync`, `sequential`
- Trigger:

  - 在 `app.unmount` 或 `app.hide` 销毁过程中出现异常则会触发该 `hook`，用户除了手动调用这两个方法外，`Garfish Router` 托管模式还会自动触发

- 示例

```ts
Garfish.run({
  ...,
  errorUnmountApp(error, appInfo) {
    console.log('子应用销毁异常', appInfo.name);
    console.error(error);
  }
})
```


### onNotMatchRouter


import Highlight from '@components/Highlight';

- Type: <Highlight> (path: string)=> void </Highlight>
  - 该 `hook` 的参数分别为：应用信息、应用实例；
- Kind: `sync`, `sequential`
- Trigger:

  - 路由发生变化当前未激活子应用且未匹配到任何子应用时触发

- 示例

```ts
Garfish.run({
  ...,
  onNotMatchRouter(path) {
    console.log('未匹配到子应用', path);
  }
})
```




---
url: /api/registerApp.md
---

# Garfish.registerApp

import Highlight from '@components/Highlight';




用于注册子应用信息，为 Garfish 实例方法。


:::info

1. `Garfish.run()` 中 apps 应用信息注册底层就是依赖 `registerApp` 的注册能力；
2. `registerApp` 为 Garfish 实例方法，用户可调用该 API 动态注册子应用信息，若出现 `Garfish.run()` 中的同名 app 应用信息，将覆盖`Garfish.run()` 中的 app 应用信息（merge, not override）；

:::

## 类型

```ts
registerApp(list: interfaces.AppInfo | Array<interfaces.AppInfo>): Garfish;
```

## 默认值

- 无

## 示例

```ts
import Garfish from 'garfish';

// 注册单个应用：
Garfish.registerApp({
  name: 'vue-app',
  basename: '/demo',
  activeWhen: '/vue-app',
  entry: 'http://localhost:3000',
  props: {
    msg: 'vue-app msg',
  },
});

// 注册多个应用
Garfish.registerApp([
  {
    name: 'vue-app',
    activeWhen: '/vue-app',
    entry: 'http://localhost:3000',
  },
  {
    name: 'react-app',
    activeWhen: '/react-app',
    entry: 'http://localhost:2000',
  },
]);
```

## Type AppInfo

> AppInfo 为子应用 app 配置类型，此配置与 Garfish.run() 全局配置中 app 相关参数含义相同。

```ts
export interface AppInfo extends AppConfig, AppLifecycle {}
```


:::info
Garfish 处理 app 参数的原则是：

1. 对于同名字段，子应用中的配置具备更高优先级；
2. 默认情况下，Garfish 使用全局配置作为每个子应用配置；
3. 针对单个子应用的信息配置不影响其它子应用；


:::

## 参数

### name

- Type: <Highlight> string </Highlight>
- 子应用名称，必选；
- 请确保每个子应用名称唯一；

### basename?


import Highlight from '@components/Highlight';

- Type: <Highlight> string </Highlight>
- 子应用的基础路径，可选，默认值为全局 [basename](/api/run#basename)；
- 通过路由驱动自动加载子应用时实际传递给子应用的 basename 为 `basename + activeWhen` 计算的值
- 若手动载入渲染应用时 `basename` 为实际传入的值
- 通过 [provider 函数](/guide/start#2导出-provider-函数) 的 `basename` 参数透传给子应用，子应用需要将 basename 设置为相应子应用的基础路由，这是必须的；
- [为什么子应用需要设置 basename ?](/issues#子应用拿到-basename-的作用)


### entry

- Type: <Highlight> string </Highlight>
- 子应用的入口资源地址，支持 HTML 和 JS 入口，必选

### domGetter?



import Highlight from '@components/Highlight';

- Type: <Highlight>interfaces.DomGetter</Highlight>

```ts
export type DomGetter =
  | string
  | (() => Element | null)
  | (() => Promise<Element>);
```

- 子应用的默认挂载点，可选，没有默认值，若省略需要在子应用 AppInfo 中单独指定。二者同时存在时，子应用指定优先级更高；
- 当提供 `string` 类型时需要其值是 `selector`, Garfish 内部会使用 `document.querySelector(domGetter)` 去选中子应用的挂载点
- 当提供 `string` 类型的 `domGetter` 时，子应用在触发渲染后并不会若当前文档流上并不存在挂载点，`Garfish` 框架内部在 `3s` 内轮讯是否有挂载点
- 当提供函数时，将在子应用挂载过程中执行此函数，并期望返回一个 dom 元素；
- 若 `domGetter` 在子应用渲染时无法查询到挂载点，则会丢出 `domGetter` 无效的异常


### props?

- Type: <Highlight> Object </Highlight>
- 初始化时主应用传递给子应用的数据，可选。子应用 [`provider` 导出函数](/guide/quickStart/start.md#2导出-provider-函数) 生命周期方法中将接收到此数据；

### sandbox?



import Highlight from '@components/Highlight';

- Type: <Highlight> SandboxConfig | false </Highlight>可选，默认值为 [全局 sandbox 配置](/api/run#sandbox)，当设置为 false 时关闭沙箱；

- SandboxConfig：

```ts
interface SandboxConfig {
  // 是否开启快照沙箱，默认值为 false：关闭快照沙箱，开启 vm 沙箱
  snapshot?: boolean;
  // 是否自动以子应用入口的域名前缀对子应用 fetch 请求的进行补齐，默认值为 false
  fixBaseUrl?: boolean;
  // 是否自动以子应用入口的域名前缀对相对路径资源进行前缀修正，默认值为 true，v1.15.0 版本提供
  fixStaticResourceBaseUrl?: boolean;
  // 是否开启开启严格隔离，默认值为 false。开启严格隔离后，子应用的渲染节点将会开启 Shadow DOM close 模式，并且子应用的查询和添加行为仅会在 DOM 作用域内进行
  strictIsolation?: boolean;
  // modules 仅在 vm 沙箱时有效，用于覆盖子应用执行上下文的环境变量，使用自定义的执行上下文，默认值为[]
  modules?: Array<Module> | Record<string, Module>;
  // disableElementtiming 1.14.4 版本提供，默认值为 false，将会给子应用元素注入 elementtiming 属性，可以通过此属性获取子应用元素的加载时间
  disableElementtiming?: boolean;
  // fixOwnerDocument  1.17.2 版本提供 ，默认值 false，目前可能会存在 ownerDocument 逃逸的情况，设置为 true 之后将会避免 ownerDocument 逃逸
  fixOwnerDocument?: boolean;
  // disableLinkTransformToStyle  1.18.0 版本提供 ，默认值 false，禁用掉 link 自动 transform 成 style 的行为
  disableLinkTransformToStyle?: boolean;
  // excludeAssetFilter 1.18.0 版本提供，默认值为 undefined，用于过滤不需要再子应用沙箱中执行的资源例如 jsonp，url 参数为对应 script 的地址，返回 true 则会过滤掉该资源
  excludeAssetFilter?: (url: string) => boolean;
}

type Module = (sandbox: Sandbox) => OverridesData | void;

export interface OverridesData {
  recover?: (context: Sandbox['global']) => void;
  prepare?: () => void;
  created?: (context: Sandbox['global']) => void;
  override?: Record<PropertyKey, any>;
}
```

- 示例

```ts
Garfish.run({
  sandbox: {
    snapshot: false,
    strictIsolation: false,
    // 覆盖子应用 localStorage，使用当前主应用 localStorage
    modules: [
      () => ({
        override: {
          localStorage: window.localStorage,
        },
      }),
    ],
  },
});
```

:::danger
请注意：
如果你在沙箱内自定义的行为将会产生副作用，请确保在 recover 函数中清除你的副作用，garfish 将在应用卸载过程中执行 recover 函数销毁沙箱副作用，否则可能会造成内存泄漏。
:::

- 在什么情况下我应该关闭 sandbox ?

  > Garfish 目前已默认支持沙箱 esModule 能力，若需要在 vm 沙箱支持 esModule 应用，请使用 `@garfish/es-module` garfish 官方插件支持此能力，但这会带来严重的性能问题，[原因](/issues/#esmodule)。如果你的项目不是很需要在 vm 沙箱下运行，此时可以关闭沙箱；

- [Garfish 沙箱机制](/guide/sandbox)

:::info
若开启快照沙箱，请注意：

1. 快照沙箱无法隔离主、子应用
2. 快照沙箱无法支持多实例（同时加载多个子应用）

:::


### activeWhen?

- Type: <Highlight> string | ((path: string) => boolean) </Highlight>
- 子应用的激活路径或激活条件，是子应用配置中的重要配置项，接收 string 和 函数类型，可选。
- `activeWhen` 使用场景为基于路由模式加载子应用时，计算当前应激活的子应用的判断条件，当使用手动加载 [loadApp](/api#loadApp) 时将忽略 `activeWhen` 选项。如果你的应用是基于路由驱动式挂载子应用，你应该始终传递 `activeWhen`；
- 在每次发生路由变化时，Garfish 都会触发 activeWhen 的校验逻辑去判断当前应该激活的子应用；

- 当参数为 string 类型时：

  - `activeWhen` 应设置为子应用的一级路由
  - Garfish 将使用字符串最短匹配原则作为激活判断条件匹配子应用，<span style={{color: '#3cee43', margin: '2px 6px'}}>各子应用的 `activeWhen` 参数应保持唯一</span>（即：Garfish 能够精准匹配到当前应该激活的子应用，应避免子应用间出现 `activeWhen` 重合的情况；

  - 在路由驱动模式下，子应用中接收到的 `basename` 参数将是 `basename` + `activeWhen`：
    <span style={{color: '#df5bf6', display: 'block', margin: '2px 6px'}}> activeWhen: '/vue-app',（basename:'/'）</span>

    - ✅ https://demo.app/vue-app
    - ✅ https://demo.app/vue-app/about
    - ✅ https://demo.app/vue-app/detail/goods
    - 🚫 https://demo.app/vue-app2
    - 🚫 https://demo.app/react-app

    <span style={{color: '#df5bf6', display: 'block', margin: '2px 6px'}}> activeWhen: '/vue-app',（basename:'/demo'）</span>

    - ✅ https://demo.app/demo/vue-app
    - ✅ https://demo.app/demo/vue-app/about
    - ✅ https://demo.app/vue-app
    - 🚫 https://demo.app/vue-app/detail/goods
    - 🚫 https://demo.app/react-app

- 当参数为 function 类型时：

  - function 将接受到参数 path，用户可在函数内定义判断逻辑，返回 `true` 表示激活当前应用，否则应返回 `false`；
  - 示例

  ```ts
  import Garfish from "garfish";
  Garfish.run({
    ...,
    apps: [
      {
        name: "vue",
        activeWhen: (path) => path.startsWith('/vue-app') || path.startsWith('/sub-app')
        entry: 'http://localhost:3000'
      }
    ]
  })
  ```

  - 校验过程中，当参数为 function 类型时，Garfish 会将当前的路径传入激活函数分割以得到子应用的最长激活路径，并将 `basename` + `子应用最长激活路径` 传递给子应用参数；

- 什么时候不需要设置 activeWhen?
  > activeWhen 为基于路由模式加载子应用时的激活路径（或条件），目的是为了寻找当前应该激活的子应用。当用户使用 [loadApp](/api#loadApp) 手动挂载应用时，此时可省略 `activeWhen` 参数。


:::danger

1. 子应用如果本身具备路由，在微前端的场景下，必须把 basename 作为子应用的基础路径，没有基础路由，子应用的路由可能与主应用和其他应用发生冲突；
2. 我们强留建议不要使用根路径作为子应用的激活条件，[为什么？](/issues/#根路由作为子应用的激活条件)


:::

### cache?

- Type: <Highlight> boolean </Highlight>
- 是否缓存子应用。若已加载过应用，在缓存模式下将返回相同的应用实例，可选，默认值为 `true`；
- Garfish 默认会对加载过的 app 进行缓存策略，目的是为了节省二次渲染开销，避免重复的编译代码造成的性能浪费，以及避免逃逸代码可能造成的内存泄漏。若关闭此选项，将会严重影响子应用的加载速度，需要仔细权衡；
- 在缓存模式下，Garfish 将不会执行子应用所有代码，仅执行 render ，可以避免逃逸代码造成的内存问题；
- 缓存模式也存在一定的弊端，关于 Garfish 的缓存机制，请移步 [Garfish 缓存机制](/guide/cache)；

### noCheckProvider

- Type: <Highlight> boolean </Highlight>
- 是否检查 `provider` 函数，可选，默认为 true；

### asyncProviderTimeout

- Type: <Highlight> number </Highlight>
- 全局异步provider超时时间，默认是2000ms，设置为0的话，只允许同步provider；
- 此项特性适用于那些不太方便处理成同步暴露provider的子应用，比如某些脚手架新建的项目，项目里看到的entry文件，实际上会被包裹一层并且动态import进来；



---
url: /api/loadApp.md
---

# Garfish.loadApp



用于手动挂载子应用，可动态控制子应用的渲染和销毁。

> Garfish 支持路由驱动式的应用挂载和销毁模式，
> 如果你的应用配置了 `activeWhen`, Garfish 则将自动监听路由变化并在路由命中时加载对应的子应用。这种模式属于路由驱动式的应用加载模式。如果你希望手动控制应用的加载和销毁，我们提供了 `Garfish.loadApp()` API 以供用户手动加载和销毁应用，这是一种更加灵活的子应用加载模式。

:::info

1. 基于路由匹配的应用加载模式会通过子应用的 `activeWhen` 参数在在路由变化后自动判断当前应加载的子应用；
2. 在手动加载模式下（Garfish.loadApp），Garfish 不会根据路径匹配而是完全由开发者控制应用加载和销毁，此时应用加载不会受到 `activeWhen` 参数的影响；

:::

## 类型

```ts
loadApp(appName: string, options?: Omit<interfaces.AppInfo, 'name'>): Promise<interfaces.App | null>;
```

## 默认值

* 无

## 示例

```jsx
import React, { useState } from 'react';
import Garfish from "garfish";
import type { interfaces } from "garfish";

// 提供 VueApp 的 React 组件
export default App = () => {
  const [app, setApp] = useState<any>(null);
  const loadApplication = async () => {
    if (!app) {
      setLoadAsync(true);
      const app = await Garfish.loadApp('vue-app', {
        cache: true,
        basename,
        domGetter: '#container',
        entry: 'http://localhost:8092',
      });
      setApp(app);
      setLoadAsync(false);
    } else {
      app.display ? app.hide() : app.show();
    }
  }

  return (
    <>
      <Button onClick={ loadApplication } >
        toggle
      </Button>
      <div id="container" >
        {loadAsync && <Spin />}
      </div>
    </>
  )
}
```

```html
<!-- 提供 ReactApp 的 Vue 组件 -->
<!-- <template>
  <div>
    <div id="container"></div>
  </div>
</template>

<script>
  import Garfish from 'garfish';
  let appInstance = null;

  export default {
    name: 'App',
    async mounted() {
      appInstance = await Garfish.loadApp('react-app', {
        cache: true,
        basename: '/react-app',
        domGetter: '#container',
        entry: 'http://localhost:8093',
      });
      // 若已经渲染触发 show，只有首次渲染触发 mount，后面渲染都可以触发 show 提供性能
      appInstance.mounted
        ? appInstance.show()
        : await appInstance.mount();
    },

    destroyed() {
      appInstance.hide();
    },
  };
```

## 参数

### name

* Type:  string&#x20;
* 要加载的子应用名称，必选。
* 各子应用的名称应保持唯一，这是子应用的唯一标识；

:::tip

1. 请确保当前要加载的子应用信息已注册。Garfish 会从已注册的 app 信息中查找同名 app，若应用信息未注册将导致应用加载失败。
2. 应用信息注册可通过 `Garfish.run()`、`Garfish.registerApp()`、`Garfish.setOptions()` 三种方式注册；

:::

### options?

* Type:  Omit `<interfaces.AppInfo, 'name'>`&#x20;

* `options` 参数含义本质上与 [registerApp](/api/registerApp.md#参数) 中同名参数保持一致，可选。

* 可移步 [registerApp](/api/registerApp.md#参数) 查看具体参数说明；这里仅针对注意事项进行说明。

:::info

> `options` 的作用？

这里提供 `options` 是允许用户在手动加载 App 时自定义当前应用的信息参数，若之前已注册过子应用，则会将已配置信息和这里的 `options` 参数进行 deepMerge，提供用户运行时更新 App 应用信息参数的能力；

值得注意的是，若已缓存过 App 实例，则再次加载会直接返回当前缓存的实例，同时 `options` 参数仍会进行 merge。若设置 `cahce: false` 关闭缓存，则会使用当前 merge 后的配置重新生成 App 实例信息并返回；

:::

* \*\* 注意事项 \*\*：
  * `options` 中不允许传递 `name` 属性，只允许更新当前 App 的应用信息参数；
  * `options` 若不传，则会默认使用已注册的应用信息参数；
  * `options` 若传递，则会覆盖已注册应用信息中的同名属性(二者进行 deepMerge)，请确保在应用信息 merge 后 `entry` 入口信息参数存在，否则将会抛出错误；
  * 子应用信息的更新不影响全局配置；

## 返回值

```ts
import Garfish from 'garfish';
import type { interfaces } from 'garfish';

let app: interfaces.App;
app = await Garfish.loadApp('vue-app', {
  cache: true,
  basename,
  domGetter: '#container',
  entry: 'http://localhost:8092',
});
```

> loadApp 的返回值为子应用的 App 实例对象，实例对象上存在一些方法和属性，提供给开发者用于手动进行 App 的挂载、销毁及判断 App 当前应用状态等信息；

### 实例属性

* &#x20;name: string&#x20;

应用名称，string。

* &#x20;mounted: boolean&#x20;

应用是否已挂载，boolean。 `true` 表示已挂载，`false` 表示未挂载。

* &#x20;display: boolean&#x20;

应用是否被隐藏，boolean。 `true` 表示显示状态，未隐藏，`false` 表示隐藏态。

* &#x20;strictIsolation: boolean&#x20;

是否开启严格隔离。`true` 表示已开启，`false` 表示未开启。

* &#x20;isHtmlMode: boolean&#x20;

是否是 `html` 入口模式。

* &#x20;appContainer: HTMLElement&#x20;

应用容器

* &#x20;appInfo: AppInfo&#x20;

应用配置信息

* &#x20;hooks: interfaces.AppHooks&#x20;
  应用生命周期钩子函数

### 实例方法

* app.mount()

  * Type

  ```ts
  mount(): Promise<boolean>
  ```

  * 示例

  ```ts
  import Garfish from 'garfish';
  import type { interfaces } from 'garfish';

  const app = await Garfish.loadApp('vue-app', {
    cache: true,
    basename,
    domGetter: '#container',
    entry: 'http://localhost:3000',
  });
  await app.mount();
  ```

  * 触发子应用的  渲染 流程。若应用 已挂载 、或 正在挂载中 、或 正在卸载中 将不会触发渲染流程；
  * 在子应用渲染前将会触发 `beforeMount` 钩子函数，渲染完成将触发 `afterMount` 钩子函数并将当前挂载的应用 push 进 `Garfish.activeApps`。若渲染过程中出现异常将触发 `errorMountApp`钩子函数；
  * 在此过程中将执行 `provider` 提供的子应用 `render` 函数，若 `provider` 函数未找到将会抛出错误。[尝试解决](/issues/index.md#provider-is-null)
  * [mount 过程中都做了哪些事情](/guide/lifecycle.md#mount)

:::info 请注意：
对于 es module 子应用(如 Vite 应用)，路由驱动模式下默认走缓存模式。子应用不可重复使用 `app.mount`，应用二次渲染只能使用 `app.show()`；

:::

* app.unmount()

  ```ts
  unmount(): boolean;
  ```

  * 触发子应用的  销毁 流程。若应用 正在卸载中 ，将不会重复卸载；
  * 在子应用渲染前将会触发 `beforeUnmount` 钩子函数，渲染完成将触发 `afterUnmount` ，若销毁过程中出现异常将触发 `errorUnmountApp` 钩子函数；
  * 应用卸载过程中会执行 `provider` 内部提供的 `destroy` 函数。卸载完成后，子应用的渲染容器将被移除、子应用的执行上下文也将被销毁，渲染过程中产生的副作用也都将会被清除，同时将子应用从
    `Garfish.activeApps` 里移除，`mounted` 和 `display` 状态置为 false；
  * [unmount 过程中都做了哪些事情](/guide/lifecycle.md#unmount)

* app.show()

  * Type

  ```ts
  show(): Promise<boolean>
  ```

  * 触发子应用的  显示 流程；

  * 示例

    ```ts
    import Garfish from 'garfish';
    import type { interfaces } from 'garfish';

    const app = await Garfish.loadApp('vue-app', {
      cache: true,
      basename,
      domGetter: '#container',
      entry: 'http://localhost:3000',
    });
    // 若已经渲染触发 show，只有首次渲染触发 mount，后面渲染都可以触发 show 提供性能
    app.mounted ? app.show() : await app.mount();
    ```

  * 触发子应用的  显示 流程。若应用 已显示 、或 未挂载  将不会触发应用渲染流程；

  * 在子应用显示前将会触发 `beforeMount` 钩子函数，显示完成将触发 `afterMount` 钩子函数并将当前挂载的应用 push 进 `Garfish.activeApps`；

  * 在此过程中将执行 `provider` 提供的子应用 render 函数，若 `provider` 函数未找到将会抛出错误。[尝试解决](/issues/index.md#provider-is-null)

  * [show 过程中都做了哪些事情](/guide/lifecycle.md#show)

:::info 请注意：

1. `app.show()` 用于触发子应用的显示流程，此过程并不是 css 中样式的显示或隐藏，show() 方法会触发子应用的 `render` 函数，若 `render` 函数中存在副作用也会再次执行；
2. `app.show()` 在应用渲染的过程中将会执行 `provider` 中提供的 `render` 函数，但与 `app.mount()` 不同的是，`app.show()` 不会创建新的执行上下文；
3. 在基于路由驱动子应用加载模式下，若已启用缓存(`cache: true`)，则会默认使用 show() 触发子应用的渲染。若未开启缓存模式，则会使用 `app.mount()` 渲染子应用。非路由驱动模式下，由开发者控制子应用的渲染和销毁；

:::

* app.hide()

  * Type

  ```ts
  hide(): boolean;
  ```

  * 触发子应用的  隐藏 流程。若应用 未显示 、或 未挂载  将不会触发应用隐藏流程；

  * 在子应用隐藏前将会触发 `beforeUnmount` 钩子函数，隐藏完成将触发 `afterUnmount` 钩子函数并将当前隐藏的应用从 `Garfish.activeApps` 中移除；

  * 在此过程中将执行 `provider` 提供的子应用 `destory` 函数。当移除完成，子应用的渲染容器也将被移除。

  * [hide 过程中都做了哪些事情](/guide/lifecycle.md#hide)



---
url: /api/loader.md
---

# Garfish.loader



`Garfish.loadApp` 底层使用 `Garfish.loader` 来进行资源加载，因此可以通过 `Garfish.loader` 来添加资源加载过程中的回调以及资源的缓存策略

## `Garfish.loader`

`Garfish.loader` 是 `Garfish` 实例上的属性，由 `Garfish` 加载器提供。该属性上提供加载资源、缓存、解析能力，可以通过 `Garfish.loader` 上的属性可控制资源的加载策略和缓存策略。

### Type

```ts
interface Garfish {
  loader: LoaderInterface;
}

interface LoaderLifecycle{
  fetch: (string, RequestInit)=> Promise<Response> | void | undefined
}

interface LoaderInterface {
  setLifeCycle: (lifeCycle: Partial<LoaderLifecycle>)=> void;
}
```

### Garfish.loader.setLifeCycle

可设置 `Garfish.loader` 在资源加载过程中的处理逻辑

#### Type

```ts
(lifeCycle: Partial<LoaderLifecycle>)=> void;
```

#### 参数

`options`

##### fetch?

* Type: LoaderLifecycle\['fetch']
* 入参: [Parameters\<LoaderLifecycle\['fetch'\]>](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters)
* 返回值: [ReturnType\<LoaderLifecycle\['fetch'\]>](https://developer.mozilla.org/en-US/docs/Web/API/fetch#return_value)
* 示例

```ts
import Garfish from 'garfish';

Garfish.registerApp({
  name: 'react',
  entry: 'http://localhost:3000/index.js'
})

// 设置 loader 的 fetch hook 返回值
// 在 Garfish 调用 http://localhost:3000/index.js 地址时，返回指定的 Response 内容
// 其他情况不处理，交由原生 fetch 发起请求
Garfish.loader.setLifeCycle({
  fetch: function(url) {
    if (url === 'http://localhost:3000/index.js') {
      return Promise.resolve(new Response(`
        console.log('hello world');
      `, {
        status: 200,
        headers: {
          'content-type': 'application/json',
        },
      }))
    },
  },
})

```

#### 说明

1. `fetch` 可以在失败重试、资源自定义缓存读取等场景中使用
2. 使用自定义 `fetch` 可以针对特定的资源进行自定义内容返回，当返回的内容为 `Promise<Response>` 实例时， Garfish 内部将不再发起 `fetch`，若返回的内容为其他类型的值将继续通过原生 `fetch` 请求资源
3. 返回的 `Response` 实例，需要携带 `status` 和 `content-type`, 若未正确携带资源类型，`Garfish` 可能无法正确识别出资源的类型



---
url: /api/preloadApp.md
---

# Garfish.preloadApp



`Garfish.preloadApp` 用于预加载特定资源，通过 `Garfish.preloadApp` 可以预加载特定子应用的入口资源和入口资源内容的子资源

## `Garfish.preloadApp`

### Type

```ts
interface Garfish {
  preloadApp: PreLoadAppType;
}

type PreLoadAppType = (appName: string)=> void
```

### 参数

#### appName

* Type:  string&#x20;
* 要加载的子应用名称，在调用 `preloadApp` 时，必须保证子应用信息已注册

#### 示例

```ts
import Garfish from 'garfish';

Garfish.registerApp({
  name: 'react',
  entry: 'http://localhost:3000'
});

// 预加载 react 子应用的入口资源和子资源（子资源表示的是，html 中携带的 script 和 link 信息）
Garfish.preloadApp('react');

```

#### 说明

1. 该 `API` 可以用于在未真正加载子应用时进行子应用的资源预加载，当资源加载成功时，真正加载子应用时将不会再发起资源请求，将直接使用独立内存中存储的静态资源
2. 通常可以将 `preloadApp` 的资源加载提升到主应用的 `html` 阶段，可以保证首屏使用到的子应用资源能够最大程度的提前完成资源的请求处理



---
url: /api/channel.md
---

# Garfish.channel



用于应用间的通信，`Garfish.channel` 为 Garfish 的实例属性，该属性是 [EventEmitter2](https://github.com/EventEmitter2/EventEmitter2) 的实例。

### Type

```ts
channel: EventEmitter2;
```

### 默认值

* 无

### 示例

```js
// 子应用监听登录事件
const App = () => {
  const handleLogin = (userInfo) => {
    console.log(`${userInfo.name} has login`);
  };

  useEffect(() => {
    window?.Garfish.channel.on('login', handleLogin);
    return () => {
      window?.Garfish.channel.removeListener('login', handleLogin);
    };
  });
};

// 主应用触发监听事件
api.getLoginInfo().then((res) => {
  if (res.code === 0) {
    window.Garfish.channel.emit('login', res.data);
  }
});
```



---
url: /api/router.md
---

# Garfish.router



用于微前端下的应用间的路由跳转，提供路守卫能力，在路由变化时触发相应hook，帮助用户更加精确的控制路由变化，灵活地支持各类业务场景。

> 路由是微前端中重要且复杂的模块。在微前端应用下，子应用既可作为独立应用运行在自己的路由系统下，又可作为子应用嵌入在主应用下加载，为了实现两种模式的无缝切换，Garfish 实现了一套路由机制保证用户在这两种模式中平滑过渡，你可以在 [Garfish 路由机制](/guide/router.md) 中了解详细设计。

:::info
在阅读下面 API 介绍之前，你需要了解和保证一些配置规范。

:::

1. 你需要了解的：

* 目前 Garfish 路由系统通过命名空间（即子应用 basename）来避免应用间的路由冲突；
* 目前 Garfish 路由系统仅支持主应用的 history 路由模式，原因是 hash 路由无法作为子应用的基础路由；
* 不要使用根路由作为子应用的激活条件，否则该应用在任何路径下都会激活，且应用间可能会产生冲突；
* 子应用在 `provider` 中的 `render` 函数拿到的 `basename` = `主应用的 basename` + `activeWhen`；

2. 你需要配置的：

* 请将 `provider` 中 `render` 函数接收到的 `basename` 设置为子应用的 `basename`，[如何配置](/guide/demo/react.md#3-根组件设置路由的-basename)；

## `Garfish.router`

`Garfish.router` 是 Garfish 实例上的属性，由 Garfish 路由系统提供。该属性上提供应用间路由跳转的方法、路由导航守卫钩子函数以及路由相关配置信息。其类型定义如下：

### Type

```ts
interface Garfish {
    router: RouterInterface;
    apps: Record<string, interfaces.App>;
}

interface RouterInterface {
    push: ({ path, query, basename}: {
        path: string;
        basename?: string;
        query?: {
            [key: string]: string;
        };
    }) => void;
    replace: ({ path, query, basename}: {
        path: string;
        basename?: string;
        query?: {
            [key: string]: string;
        };
    }) => void;
    beforeEach: (hook: RouterHook) => void;
    afterEach: (hook: RouterHook) => void;
    registerRouter: (Apps: interfaces.AppInfo | Array<interfaces.AppInfo>) => void;
    routerChange: (hook: RouterChange) => void;
    setRouterConfig: typeof setRouterConfig;
    listenRouterAndReDirect: ({ apps, basename, autoRefreshApp, active, deactive, notMatch}: Options$1) => void;
    routerConfig: Options$1;
}
```

### 默认值

* 无

### Garfish.router.push

路由导航方法。

#### Type

```ts
push: ({ path, query, basename}: {
      path: string;
      basename?: string;
      query?: {
          [key: string]: string;
      };
  }) => void;
```

#### 参数

* path

  要跳转的路由，`string`，必选。
* basename

  设置跳转的基础路由，`string`，非必选。
* query

  路由携带的查询参数，`Record<string, string>`，非必选。

#### 示例

```ts
import Garfish from 'garfish';

// 跳转 vue-a 应用：
Garfish.router.push({
  path: '/vue-a'
});

// 跳转 react-b 应用详情页：
Garfish.router.push({
  path: "/react-b/detail",
  query: { id: "002" },
});
```

#### 说明

1. `Garfish.router.push()` 方法默认会携带上全局 basename 作为跳转前缀，若使用框架自身路由进行跳转，请记得主动添加`basename` 跳转前缀。下面两种跳转方式等价：

```ts
Garfish.router.push({ path: '/react-b' });
navigate('/examples/react-b'); // navigate 为 react-router-dom v6 跳转方法
```

2. 此方法会向 history 栈添加新的记录，点击浏览器后退按钮后能正常返回上一个页面；
3. 若跳转子应用的子路由，使用 `Garfish.router.push()` 方法跳转将触发子应用子路由视图更新。另外若关闭 [autoRefreshApp](/api/run.md#autorefreshapp) 选项，则将**只能**使用 `Garfish.router` 进行跳转子应用子路由，但子应用一级路由仍将可使用框架路由跳转。
4. 本 api 可以在 react-router-prompt 触发多次时，配合 autoRefreshApp 配置。关闭其他跳转方法触发子应用刷新组件，可限制 prompt 触发多次或子应用额外卸载多次的场景。

:::info
由于目前主流框架并不是通过监听路由变化来触发组件的更新的。在跳转子应用子路由时，若直接使用 `history.pushState` 将不会触发对应路由的组件更新，请使用 `Garfish.router` 提供的方法进行跳转。

:::

### Garfish.router.replace

路由导航方法。

#### Type

```ts
replace: ({ path, query, basename}: {
      path: string;
      basename?: string;
      query?: {
          [key: string]: string;
      };
  }) => void;
```

#### 参数

* path

  要跳转的路由，`string`，必选。
* basename

  设置跳转的基础路由，`string`，非必选。
* query

  路由携带的查询参数，`Record<string, string>`，非必选。

#### 示例

```ts
import Garfish from 'garfish';
// 跳转 react-a 应用：
Garfish.router.replace({
  path: '/react-a'
});
```

#### 说明

1. `Garfish.router.replace()` 方法与 [Garfish.router.push()](/api/router.md#garfishrouterpush) 方法类似，唯一的区别是：它不会向 history 添加新记录，而是跟替换掉当前的 history 记录；
2. 其它参数请参考 [Garfish.router.push()](/api/router.md#garfishrouterpush)

### Garfish.router.beforeEach

#### 触发时机

* 全局路由守卫，在**路由跳转后**，**子应用挂载前**触发。

#### Type

```ts
beforeEach: (hook: RouterHook) => void;

type RouterHook = (
  to: CurrentRouterInfo,
  from: CurrentRouterInfo,
  next,
) => void;

export interface CurrentRouterInfo {
  fullPath: string;
  path: string;
  query: Object;
  state: Object;
  matched: Array<interfaces.AppInfo>;
}
```

#### 参数

* to
  ：即将要进入的目标路由信息。

* from
  ：即将离开的路由信息。

* next
  ：阻塞执行回调。

#### 示例

```ts
import Garfish from 'garfish';
Garfish.router.beforeEach((to, from, next) => {
  next();
});

Garfish.run({...})
```

### Garfish.router.afterEach

#### 触发时机

* 全局路由守卫，在**路由跳转后**，**子应用挂载后**触发。

#### Type

```ts
afterEach: (hook: RouterHook) => void;

type RouterHook = (
  to: CurrentRouterInfo,
  from: CurrentRouterInfo,
  next,
) => void;

export interface CurrentRouterInfo {
  fullPath: string;
  path: string;
  query: Object;
  state: Object;
  matched: Array<interfaces.AppInfo>;
}
```

#### 参数

* to
  ：即将要进入的目标路由信息。

* from
  ：即将离开的路由信息。

* next
  ：阻塞执行回调。

#### 示例

```ts
import Garfish from 'garfish';
Garfish.router.afterEach((to, from, next) => {
  next();
});

Garfish.run({...})
```

### Garfish.router.routerChange

#### 触发时机

* 全局路由守卫，在**路由发生变化**，**子应跳转前**触发。

#### Type

```ts
afterEach: (path: string) => void;
```

#### 参数

* path
  ：跳转到的<code>location.pathname</code>。

#### 示例

```ts
import Garfish from 'garfish';
Garfish.router.routerChange(path => {
  console.log(path);
});

Garfish.run({...})
```

:::tip
请注意：

1. `Garfish.router.beforeEach`、`Garfish.router.afterEach` 和 `Garfish.router.routerChange` 均属于 Garfish 提供的路由守卫钩子，将在每次在路由变化后触发。
2. `Garfish.router.beforeEach`、`Garfish.router.afterEach` 和 `Garfish.router.routerChange` 是**全局唯一的**，如果设置多次，那么只有最后执行的是有效的。对它们的使用应该需要一定的约定，避免多次注册导致互相覆盖。
3. 请将路由守卫注册放在 `Garfish.run` 前执行，否则将无法接收到首次加载时的路由钩子；
4. 若跳转新的子应用，则 `Garfish.router.beforeEach` 将在子应用加载前触发，`Garfish.router.afterEach` 将在子应用加载后触发。此时路由均已发生变化；
5. `next` 函数可为异步函数，微前端渲染流程将被阻塞直至 `next` 函数被 resolve。
6. 在子应用间跳转时，若使用了路由守卫钩子，请确保 `next` 函数被执行，否则将导致 Garfish 内部子应用渲染逻辑被阻塞；
7. 子应用内路由跳转不受 `next` 函数调用的影响；

:::



---
url: /api/setOptioins.md
---

# Garfish.setOptions

在 `Garfish.run` 调用前用于动态更新配置信息的API，参数与 [Garfish.run](/api/run) 保持一致。
## 设计初衷
在某些场景下，微前端应用的初始化参数信息在运行过程中可能会出现混乱不一致的情况，提供该 `API` 用于用户在复杂场景下设置全局微前端应用参数信息，此 API 作用于全局 Garfish 实例。


:::info
`Garfish.setOptions` 用于微前端应用启动前的参数变更。在触发了 `run` 方法后，不可以再通过 `setOptions` 更改应用配置。

:::

## 示例

```js
// 主应用 index.js
import Garfish from 'garfish';

Garfish.setOptions({
  basename: '/',
  domGetter: '#container',
  // xxx
});
```

## 参数

`Options`

- 此 API 参数与 [Garfish.run](/api/run) 保持一致。 请参考 [Garfish.run](/api/run#参数)；



---
url: /api/setExternal.md
---

# Garfish.setExternal

用于实现主、子应用间依赖共享。


:::tip
1. 主、子应用若开启进行依赖共享能力，需要构建成 'umd' 规范且保证 `jsonpFunction` 唯一；[参考](/guide/build-config)；
2. 若子应用通过依赖共享主应用核心包，则子应用将不能独立运行；
3. 主应用的若升级版本会可能会对子应用产生影响；
4. external 的内容会逃逸 vm 沙箱；

:::

> 请注意，Garfish.setExternal 是 garfish 提供的用于实现应用间的依赖共享的 API，通过该 API 可将依赖进行注册并在注册完成后可实现主子应用的依赖共享。但可能会由于共享带来某些依赖的影响，若出现问题我们建议关闭共享机制。

## 类型
```ts
setExternal(nameOrExtObj: string | Record<string, any>, value?: any): Garfish;
```
## 示例
### 主应用

- 主应用 webpack 配置
```js
// 主应用 webpack.config.js
module.exports = {
  output: {
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 请求确保该值与子应用的值不相同避免与子应用发生影响
    jsonpFunction: 'main-app-jsonpFunction'
  },
};
```
- 设置 external
```ts
// 主应用 index.ts
import React from 'react';
import * as ReactDom from 'react-dom';
import * as mobxReact from 'mobx-react';
import * as ReactRouterDom from 'react-router-dom';
import Garfish from 'garfish';

Garfish.setExternal({
  react: React,
  'react-dom': ReactDom,
  'react-router-dom': ReactRouterDom,
  'mobx-react': mobxReact,
});
```
### 子应用

```js
// 子应用 webpack.config.js
module.exports = {
  output: {
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // 请求确保每个子应用该值都不相同，否则可能出现 webpack chunk 互相影响的可能
    jsonpFunction: 'vue-app-jsonpFunction',
    // 保证子应用的资源路径变为绝对路径，避免子应用的相对资源在变为主应用上的相对资源，因为子应用和主应用在同一个文档流，相对路径是相对于主应用而言的
    publicPath: 'http://localhost:8000'
  },
  externals: {
    react: 'react',
    'react-dom': 'react-dom',
    'react-router-dom': 'react-router-dom',
    'mobx-react': 'mobx-react'
  }
};
```



---
url: /api/setGlobal.md
---

# Garfish.setGlobalObject

用于子应用设置真实 window 的值。

> 在微前端应用下，子应用将默认开启沙箱模式。在沙箱模式下，子应用中全局变量为被 proxy 的 'fakeWindow'，而全局变量（真实 window）默认会被隔离。若子应用需求设置真实 window 的值，可以通过此方法获取。


:::tip
1. 一般情况下我们不建议直接通过此 API 设置真实 window；
2. 若需要设置真实 window 上的环境变量，可通过 [`protectVariable`](/api/run#protectvariable) 属性，将需要共享的属性放入列表中即可通过子应用的全局变量获取；

:::

## Type
```ts
setGlobalValue(key: string, value?: any): void;
```
## 示例

```ts
import Garfish from 'garfish';

Garfish.setGlobalValue(key: string | symbol, value: any);
```



---
url: /api/getGlobal.md
---

# Garfish.getGlobalObject



用于子应用获取真实 window 的值。

> 在微前端应用下，子应用将默认开启沙箱模式。在沙箱模式下，子应用中全局变量为被 proxy 的 'fakeWindow'，而全局变量（真实 window）默认会被隔离。若子应用需求获取真实 window 的值，可以通过此方法获取。

:::tip

1. 一般情况下我们不建议直接通过此 API 获取真实 window，这样建议的原因是：
   * 使用此 API 后子应用产生了一个无法独立运行的逻辑，导致子应用失去独立运行的能力；
   * 由于环境变量的修改并不是单向数据流，造成主应用无法感知哪些子应用会去修改 window 上的哪些变量，可能造成数据管理的混乱；

2. 若需要获取真实 window 上的环境变量，可通过 [`protectVariable`](/api/run.md#protectvariable) 属性，将需要共享的属性放入列表中即可通过子应用的全局变量获取，这样主应用能感知到哪些值是会被修改的，哪些值是不会被修改的，能在一定程度上控制 `window` 变量的修改；

:::

## Type

```ts
getGlobalObject: () => Window & typeof globalThis;
```

## 示例

```js
import Garfish from 'garfish';

const nativeWindow = Garfish.getGlobalObject();
```



---
url: /api/clearEscapeEffect.md
---

# Garfish.clearEscapeEffect

用来清除逃逸沙箱的变量。

> 在微前端应用下，子应用将默认开启沙箱模式。在沙箱模式下，若发现有一些特殊的行为会逃逸沙箱系统，可以使用此方法来清除逃逸的变量；

## Type
```ts
clearEscapeEffect: (key: string, value?: any) => void;
```

## 示例

```js
Garfish.clearEscapeEffect('webpackJsonp');
```



---
url: /blog/__meta__.md
---




---
url: /blog/architecture.md
---

# 微前端架构设计

微前端是什么：微前端是一种类似于微服务的架构，是一种由独立交付的多个前端应用组成整体的架构风格，将前端应用分解成一些更小、更简单的能够独立开发、测试、部署的应用，而在用户看来仍然是内聚的单个产品。

微前端诞生在两个大的背景下，在提倡拥抱变化的前端社区可以看到新的框架、技术、概念层出不穷，并且随着 Web 标准的演进，前端应用已经具备更好的性能、更快的开发效率。但随着而来的是应用的复杂程度更高、涉及的团队规模更广、更高的性能要求，应用复杂度已经成为阻塞业务发展的重要瓶颈。

微前端就是诞生于 Web 应用日益复杂化的场景中，因为随着网络速度、计算机硬件水平的提升和 Web 标准的演进，过去 Web 应用用户体验远不如传统的应用软件时代已逐渐远去，两者之间在用户体验上的差距不断缩减，并且由于 Web 应用开发速度快、用完即走等特性，导致的一个最终结果就是「能用 Web 技术实现的应用，最终都会通过 Web 来实现」。在近几年涌现了一大批之前只能在传统 PC 软件中才能看到的优秀产品，例如：Photoshop、Web Office、Web IDE。尽管随着 Web 标准的演进，前端工程化也在不断演变，从模块化到组件化在到现在的工程化，但在面对跨团队大规模开发、跨团队企业级应用协作，现有的分治设计模式仍然显得有心无力。

![image](https://user-images.githubusercontent.com/27547179/165336394-c724ee52-01a6-4667-9765-2b6c95c07ca6.png)

## 大规模 Web 应用的困局

尽管 Web 应用的复杂度和参与人数以爆炸式的增长速度，但却没有一种新的架构模式来解决现有的困境，并同时兼顾 `DX`（developer experience）和 `UX`（user experience）。

以字节跳动内「研发中台」举例，在研发日常工作中需要使用非常多的研发系统，例如：代码管理、代码构建、域名管理、应用发布、CDN 资源管理、对象存储等。站在整个公司研发的角度考虑，最好的产品形态就是将所有的研发系统都放置同一个产品内，用户是无法感知他在使用不同的产品，对于用户而言就是单个产品不存割裂感，也不需要去学习多个平台，仅仅需要学习和了解字节跳动内的「研发中台」即可。

在字节跳动内这一类应用随处可见，由于字节跳动内存在大量业务线，每一条业务线都会诞生大量的中台系统，并且还在指数增长，以字节跳动内电商业务举例，对于电商运营的日常工作来说，其实与研发日常工作一样，围绕在：商品、商家、品牌、风控、营销等工作上，那么对于电商运营来说怎么样才最高效的电商运营系统呢，由于整个系统涉及范围较广，在实际的研发过程中必然会以功能或业务需求垂直的切分成更小的子系统，切分成各种小系统后尽管由于分治的设计理念提升了开发者体验，但是一定程度上降低了用户体验。那能否以一种新的架构模式，既保开发者体验，又能提升用户体验呢。

### 传统 Web 应用的利与弊

这里简单分析一下传统 Web 应用在开发大规模应用和涉及多研发团队协作时遇到的一些困境，以上面案例中的「电商运营平台」举例，对于电商运营而言商品、商家、品牌等都是电商运营平台能力的一部分，而不是独立之间的孤岛。若以传统的前端研发模式进行开发，那么此时有两种项目设计策略：

1. 将平台内多个系统放置同一个代码仓库维护 ，采用 `SPA`（Single-page Application） 单页应用模式
2. 将系统分为多个仓库维护，在首页聚合所有平台的入口，采用 `MPA`（Multi-page Application）多页应用模式

若采用多个系统放置同一个项目内维护：

- 优势：
  - 统一的权限管控、统一的 Open API 开发能力
  - 更好的代码复用，基础库复用
  - 统一的运营管理能力
  - 不同系统可以很好的通信
  - SPA 应用特有优势：
    - 更好的性能
    - 具备局部更新，无缝的用户体验
    - 提前预加载用户下一页的内容
- 劣势：
  - 代码权限管控问题
  - 项目构建时间长
  - 需求发布相互阻塞
  - 代码 commit 混乱、分支混乱
  - 技术体系要求统一
  - 无法同时灰度多条产品功能
  - 代码回滚相互影响
  - 错误监控无法细粒度拆分

采用方案一的劣势非常明显，在日常开发中研发：代码构建半小时以上、发布需求时被需求阻塞、无法局部灰度局部升级、项目遇到问题时回滚影响其他业务、无法快速引进新的技术体系提高生产力，项目的迭代和维护对于研发同学而言无疑是噩梦。

尽管降低了开发体验，如果对项目整体的代码拆分，懒加载控制得当，其实对于使用平台的用户而言体验却是提升的，这一切都归因于 SPA 应用带来的优势，SPA 应用跳转页面时无需刷新整个页面，路由变化时仅更新局部，不用让用户产生在 MPA 应用切换时整个页面刷新带来的抖动感而降低体验，并且由于页面不刷新的特性可以极大程度的复用页面间的资源，降低切换页面时带来的性能损耗，用户也不会感知他在使用不同平台。

若采用拆分成多个仓库维护

- 优势
  - 可以以项目维度拆分代码，解决权限管控问题
  - 仅构建本项目代码，构建速度快
  - 可以使用不同的技术体系
  - 不存在同一个仓库维护时的 commit 混乱和分支混乱等问题
  - 功能灰度互不影响
- 劣势
  - 用户在使用时体验割裂，会在不同平台间跳转，无法达到 SPA 应用带来的用户体验
  - 只能以页面维度拆分，无法拆分至区块部分，只能以业务为维度划分
  - 多系统同灰度策略困难
  - 公共包基础库重复加载
  - 不同系统间不可以直接通信
  - 公共部分只能每个系统独立实现，同一运维通知困难
  - 产品权限无法进行统一收敛
    采用方案二在一定程度上提升了开发体验，但却降低了用户体验，研发在日常开发工作中需要使用大量的平台，但是却需要跳转到不同的平台上进行日常的研发工作，整体使用体验较差。体验较差的原因在于将由于通过项目维度拆分了整体「研发中台」这样的一个产品，使各个产品之间是独立的孤岛，系统间相互跳转都是传统意义上的 MPA，跳转需要重新加载整个页面的资源，除了性能是远不如 SPA 应用的并且应用间是没法直接通信，这就进一步增强了用户在使用产品时的割裂感。

### 背景和意义总结

通过以上两个场景案例，其实可以发现由于 Web 应用在逐步取代传统的 PC 软件时，大规模 Web 应用在面对高复杂度和涉及团队成员广下无法同时保证 DX 和 UX 的困境。传统的分而治之的策略已经无法应对现代 Web 应用的复杂性，因此衍生出了微前端这样一种新的架构模式，与后端微服务相同，它同样是延续了分而治之的设计模式，不过却以全新的方法来实现。

## 微前端解决方案

上一节总结了微前端出现的背景和意义，并且了解了两种传统 Web 应用的研发模式：SPA（Single-page Application）、MPA（Multi-page Application）在涉及人员广和项目复杂度高的场景下带来的劣势，那么期望能有一种新的架构能同时具备 SPA 和 MPA 两种架构优势，并同时提升 DX（developer experience）和 UX（user experience）呢？

那在理想的情况下，期望能达到，将一个复杂的单体应用以功能或业务需求垂直的切分成更小的子系统，并且能够达到以下能力：

- 子系统间的开发、发布从空间上完成隔离
- 子系统可以使用不同的技术体系
- 子系统间可以完成基础库的代码复用
- 子系统间可以快速完成通信
- 子系统间需求迭代互不阻塞
- 子应用可以增量升级
- 子系统可以走向同一个灰度版本控制
- 提供集中子系统权限管控
- 用户使用体验整个系统是一个单一的产品，而不是彼此的孤岛
- 项目的监控可以细化到到子系统

那么基于上面理想情况，如何从零设计一套全新的架构用于解决现代 Web 应用在面对企业级系统遇到的困境呢。

## 微前端的整体架构

那么如何提供一套解决方案既具备 SPA 的用户体验，又能够具备 MPA 应用带来的灵活性，并且可以实现应用间同灰度，监控也可能细化到子系统呢。目前在字节跳动内应用的微前端解决方案「Garfish」 ，解决方案主要分为三层：部署侧、框架运行时、调试工具，目前采用的是 SPA 的架构。

![image](https://user-images.githubusercontent.com/27547179/165336487-d02e8b09-239b-4108-8351-de33d8f3bb1c.png)
![image](https://user-images.githubusercontent.com/27547179/165336535-8939d56e-0244-41d5-9d1c-b103d8743cc4.png)

### 微前端部署平台

部署平台作为微前端研发流程中重要的一环，主要提供了：微前端的服务发现、服务注册、子应用版本控制、多个子应用间同灰度、增量升级子应用、下发子应用信息列表，分析子应用依赖信息提取公共基础库降低不同应用的依赖重复加载。
用于解决微前端中子应用的独立部署、版本控制和子应用信息管理，通过 Serverless 平台提供的接口或在渲染服务中下发主应用的 HTML 内容中包含子应用列表信息，列表中包括了子应用的详细信息例如：应用 id、激活路径、依赖信息、入口资源等信息，并通过对于子应用的公共依赖进行分析，下发子应用的公共依赖，在运行时获取到子应用的信息后注册给框架，然后在主应用上控制子应用进行渲染和销毁。

![image](https://user-images.githubusercontent.com/27547179/165336565-b18887cf-8069-4bd1-b12a-3e80bc4277ca.png)

### 微前端运行时

> Why not iframe

谈到微前端绕不开的话题就是为什么不适用 iframe 作为承载微前端子应用的容器，其实从浏览器原生的方案来说，iframe 不从体验角度上来看几乎是最可靠的微前端方案了，主应用通过 iframe 来加载子应用，iframe 自带的样式、环境隔离机制使得它具备天然的沙盒机制，但也是由于它的隔离性导致其并不适合作为加载子应用的加载器，iframe 的特性不仅会导致用户体验的下降，也会在研发在日常工作中造成较多困扰，以下总结了 iframe 作为子应用的一些劣势：

- 使用 Iframe 会大幅增加内存和计算资源，因为 iframe 内所承载的页面需要一个全新并且完整的文档环境
- Iframe 与上层应用并非同一个文档上下文导致
  - 事件冒泡不穿透到主文档树上，焦点在子应用时，事件无法传递上一个文档流
    - 主应用劫持快捷键操作
    - 事件无法冒泡顶层，针对整个应用统一处理失效
  - 跳转路径无法与上层文档同步，刷新丢失路由状态
  - Iframe 内元素会被限制在文档树中，视窗宽高限制问题
  - Iframe 登录态无法共享，子应用需要重新登录
  - Iframe 在禁用三方 cookie 时，iframe 平台服务不可用
  - Iframe 应用加载失败，内容发生错误主应用无法感知
  - 难以计算出 iframe 作为页面一部分时的性能情况
- 无法预加载缓存 iframe 内容
- 无法共享基础库进一步减少包体积
- 事件通信繁琐且限制多

### 基于 SPA 的微前端架构

尽管难以将 `Iframe` 作为微前端应用的加载器，但是却可以参考其设计思想，一个传统的 `Iframe` 加载文档的能力可以分为四层：文档的加载能力、HTML 的渲染、执行 JavaScript、隔离样式和 JavaScript 运行环境。那么微前端库的基础能力也可以参考其设计思想。
从设计层面采取的是基座+子应用分治的概念，部署平台负责进行服务发现和服务注册，将注册的应用列表信息下发至基座，通过基座来动态控制子系统的渲染和销毁，并提供集中式的模式来完成应用间的通信和应用的公共依赖管理，因此 Garfish 在 Runtime 层面主要提供了以下四个核心能力：

- 加载器（Loader）
  - 负责注册平台侧提供的应用列表
  - 负责加载和解析子应用入口资源
    - HTML 入口类型，拆解 HTML Dom、Script、Style
    - JS 入口类型，提供基础 Dom 容器
  - 预加载能力
  - 解析子应用导出内容
- 沙箱隔离（Sandbox）
  - 提供代码执行能力，收集执行代码时存在的副作用
  - 提供销毁收集副作用的能力
  - 支持沙箱多实例，收集不同实例的副作用
- 路由托管（Router）
  - 解决不同应用间的路由不同步问题
  - 提供路由劫持能力，在主应用上管控子应用路由
  - 提供路由驱动能力来拼装完整的平台的能力
- 子应用通信（Store）
  - 建立通信桥梁
  - 提供共享机制

![image](https://user-images.githubusercontent.com/27547179/165336609-b903adc8-7978-4776-a966-104a251e0555.png)

### 应用生命周期

整个微前端子应用的生命周期基本可以总结为：

- 渲染阶段
  - 主应用通过路由驱动或手动挂载的方式触发子应用渲染
  - 开始加载应用的资源内容，并初始化子应用的沙箱运行时环境
  - 判断入口类型
    - 若入口类型为 `HTML` 类型，将开始解析和拆解子应用资源
    - 若入口类型为 `JS`，创建子应用的挂点 `DOM`
  - 将子应用存在”副作用“（对当前页面可能产生影响的内容）交由沙箱处理
  - 开始渲染子应用的 `DOM` 树
  - 触发子应用的渲染 `Hook`
- 销毁阶段
  - 若路由变化离开子应用的激活范围或主动触发销毁函数，触发应用的销毁
  - 清除应用在渲染时和运行时产生的副作用
  - 移除子应用的 `DOM` 元素

![image](https://user-images.githubusercontent.com/27547179/165336638-d344a74b-ec15-43c1-958e-5dcec9e045fc.png)

### 加载器的设计

加载器的整体设计理念其实与 `React-loadable` 非常类似，具备以下能力：

- 异步加载组件资源
- 可以预加载资源
- 可以缓存组件资源
- 缓存组件实例

与组件不同的是微前端作为一种能够将单体应用拆解成多个子应用的架构模式，不同于组件，这些被拆分出去的子应用最好的研发模式是在开发、测试、部署都与宿主环境分离，子应用本身应具备自治能力，那么此时就与 Iframe 提供的能力非常类似，Iframe 通过加载 HTML 文档的形式加载整个子应用的资源，那么子应用本身就可作为一个独立站点，天然具备独立开发、测试的能力。因此 Garfish 的加载器提供了两种应用入口类型：HTML 类型和 JS 入口类型，但需要注意的是 Garfish 并非像 Iframe 一样将其分为了另一个文档流，而是将其与主应用作为同一个文档流处理，用以规避其不在同一个文档流带来的体验感割裂问题。

由于 HTML 入口类型天然具备独立、开发、测试的特性，在微前端整体架构设计中，对于跨团队协作而言，最好的研发模式是能降低其沟通成本，而降低沟通成本的最好方式是不沟通，所以一般项目类型都尽可能的推荐用户使用 HTML 的入口类型。

那么针对 HTML 入口类型的加载器需要做一些什么呢，下面是一张浏览器的渲染过程图：

![image](https://user-images.githubusercontent.com/27547179/165336682-bbf6625a-eb49-4546-8f05-ff12d473c4d9.png)

针对浏览器的渲染过程也可将其分为：`HTML` 文本下载、 `HTML` 拆解为语法树、拆解语法树中具备”副作用的内容“（对当前页面可能产生影响的内容）如 `Script`、`Style`、`Link` 并交由沙箱处理进行后渲染，与一般的子应用不同的是需要子应用提供 `provider`，`provider` 中包含了子应用渲染和销毁的生命周期，这两个 `Hook`可以应用缓存模式中进一步增强应用的渲染速度和性能。

![image](https://user-images.githubusercontent.com/27547179/165336727-3489f2e6-20a9-4722-89f8-a3291fab8569.png)

### 沙箱的设计

其实在过去的 Web 应用中是很少提及到沙箱这一概念的，因为组件的开发一般都会由研发通过研发规范来尽可能的去避免组件对当前应用环境造成副作用，诸如：组件渲染后添加了定时器、全局变量、滚动事件、全局样式并且在组件销毁后会及时的清除子应用对当前环境产生的副作用。
与组件完全不同的是微前端是由多个独立运行的应用组成的架构风格，这些系统可能分别来自不同的技术体系。项目的开发、测试从空间和时间上都是分离的，由于没有 Iframe 一样原生能力的隔离很难应用间不发生冲突，这些冲突可能会导致应用发生异常、报错、甚至不可用等状态。

以 Webpack4 JsonpFunction 为例
在 Webpack5 中提供了一个重要的功能就是 Module Federation，随着 Webpack 5 推出 Module Federation ，与 Webpack 4 发生变化的一个重要配置就是 JsonpFunction 属性变为了 chunkLoadingGlobal，并且由原来的默认值 webpackJsonp 变成了默认使用 output.library 名称或者上下文中的 package.json 的 包名称(package name)作为唯一值（webpack.js.org/issues/3940）。

为什么会发生这个转变呢，如果了解过 Webpack 构建产物的一定会知道 Webpack 通过全局变量存储了分 chunk 后的产物，用于解决分包 chunk 的加载问题。由于 Webpack 5 引入 Module Federation 页面中可能会同时存在两个以上的 Webpack 构建产物，如果还是通过同一个变量存储要加载的 chunk ，必然会造成产物之间的互相影响。

通过 Webpack 4 到 Webpack 5 支持 Module Federation 之后可以发现，在一个基础库尚未考虑默认兼容多实例的场景下，贸然将其作为多实例使用很可能会造成应用无法按照预期运行，更为严重的是你以为其正常运行了其实应用已经发生了严重的内存泄漏或不可预知的情况，倘若将 Webpack 构建产物的应用多次动态的在页面中运行，将会发现已经造成严重的内存泄漏，因为 Webpack 会增量的向全局存储 chunk 的变量上挂载模块以及依赖信息，简单来说就是每次执行 Webpack 构建的子应用代码都会向 webpackJsonp 数组 push 大量的数据，最终造成内存泄漏，直至页面崩溃。

#### 沙箱的核心能力

为了保证应用能够稳定的运行且互不影响，需要提供安全的运行环境，能够有效地隔离、收集、清除应用在运行期间所产生的副作用，那应用运行期间主要会产生哪些副作用呢，可以将其分为以下几类：全局变量、全局事件、定时器、网络请求、`localStorage`、`Style` 样式、`DOM` 元素。

在 Garfish Runtime 中的沙箱主要能力也是围绕在这一块的能力建设上，针对子应用可能产生的副作用类型主要分为两类，一类是：静态副作用、另一类则是：动态副作用。这里静态副作用和动态副作用分别指的是什么呢，静态副作用指的是 HTML 中静态标签内容例如：Script 标签、Style 标签、Link 标签，这些内容属于在 HTML 文档流中就包含的，另外一部分副作用属于动态副作用，动态副作用指的是由 JavaScript 动态创建出来的，例如 JavaScript 可以动态创建 Style、动态创建 Script、动态创建 Link、动态执行代码、动态添加 DOM 元素、添加全局变量、添加定时器、网络请求、localStorage 等对当前页面产生副作用的内容。

针对子应用的静态副作用的收集比较简单，Loader 核心模块上已经提供了子应用入口资源类型的分析和拆解，可以从子应用 DOM 树中轻松拆解获取副作用内容，那么对于静态副作用已经可以完成有效的收集、清除，但是尚未具备隔离的能力。动态创建的副作用都是通过 JavaScript 来动态创建的，需要收集到 JavaScript 运行时产生的副作用，并提供副作用的隔离和销毁能力。

#### 沙箱设计的两种思路

在 Garfish 微前端中，如何有效收集、隔离、清除应用的副作用是保障应用能够平稳运行的核心能力之一。沙箱的主要能力也在于能够捕获动态创建的副作用，对应用的副作用进行隔离和清除。

那么如何能够有效的捕获到动态创建的副作用、收集、并隔离呢？目前 Garfish 提供了两种设计思路，一种是快照模式，另外一种是 VM 模式。

快照沙箱：顾名思义，在应用运行前通过快照的模式来保存当前执行环境，在应用销毁后恢复回应用之前的执行环境，用于实现应用间副作用的隔离和清除。类似于 “SL 大法”，通过 save 存储环境，通过 load 加载环境的模式。

代码实现思路

![image](https://user-images.githubusercontent.com/27547179/165336764-027a864a-6fd5-4420-ac98-28d2301ae0a5.png)

核心设计思想简述：

1. 针对每一种副作用提供一个 Patch 类，这个类需要提供 save 和 load 两个方法
2. Save 对应着该副作用的环境快照存储，Load 对应着销毁该副作用的销毁恢复环境
3. 并且针对每一种 Patch 还可以存储其在运行期间发生的变化，在优化场景时并不用所有代码，仅恢复执行环境即可

###### VM 沙箱

通过快照沙箱的最简化的核心实现后可以发现，它的设计理念依赖于整个代码的执行属于线性的过程，即：存储执行环境=>执行具备副作用的代码=>恢复执行环境，但在实际的场景中对于应用的划分并非以页面为维度划分，同一个页面可能存在多个应用，所以它的执行顺序并非线性，可能同时存在多个快照沙箱的实例环境，也就是快照沙箱多实例，以下面代码举例：

![image](https://user-images.githubusercontent.com/27547179/165336842-861d7e28-8c61-476d-9eb0-cfee04415e09.png)

通过上面的代码可以发现，在同时运行多个快照沙箱实例时，在代码执行顺序非线性的场景下，并不能有效的收集和处理应用的副作用，也基于此快照沙箱无法使用在非线性呢多实例的场景中，因此也进一步推出了 VM（virtual machine） 沙箱。

维基百科关于 VM 的解释：在计算机科学中的体系结构里，是指一种特殊的软件，可以在计算机平台和终端用户之间创建一种环境，而终端用户则是基于虚拟机这个软件所创建的环境来操作其它软件。虚拟机（VM）是计算机系统的仿真器，通过软件模拟具有完整硬件系统功能的、运行在一个完全隔离环境中的完整计算机系统，能提供物理计算机的功能。

在 Node 中也提供了 VM 模块，不过不过不同于传统的 VM，它并不具备虚拟机那么强的隔离性，并没有从模拟完整的硬件系统，仅仅将指定代码放置在特定的上下文中编译并执行代码，所以它无法用于不可信来源的代码。

参考 Node 中 VM 模块的设计，以及 JavaScript 词法作用域 的特性，可以设计出 VM 沙箱，不过与传统的 VM 差异也同样存在，它并能执行不可信的代码，因为它的隔离能力仅限于将其运行在一个指定的上下文环境中。

从而得出以下设计

![image](https://user-images.githubusercontent.com/27547179/165336890-1f3ea38f-33b6-4eea-abad-4e928bdcddea.png)

![image](https://user-images.githubusercontent.com/27547179/165336915-6bbb2ecd-4fef-4c7c-9d19-9d3b72ba3497.png)

隔离环境需要哪些上下文
针对副作用的类型：全局变量、全局事件、定时器、网络请求、localStorage、Style 样式、DOM 元素，分别提供了全新的执行上下文：

- Window
  - 用于隔离全局环境
- document
  - 用于捕获动态创建的 DOM 节点、Style、Script
    - 收集 DOM 副作用
    - 收集 Style 副作用，进行处理
    - 收集 Script，继续放置沙箱处理
- timeout、interval
  - 处理定时器
- localstorage
  - 隔离 localStorage
- listener
  - 收集全局事件

新的执行上下文哪里来
新的执行上下文有两个来源，

- 来源于当前环境
- 来源于 Iframe 的执行环境
  由于 Iframe 创建后需要需要较多的内存资源和计算资源，而微前端中的 VM 沙箱并不需要一个完全的执行上下文，所以可以基于当前环境。

![image](https://user-images.githubusercontent.com/27547179/165336962-e61778cb-a953-41d5-99b8-6b8234eb808f.png)

快照沙箱和 VM 沙箱能力对比

![image](https://user-images.githubusercontent.com/27547179/165336996-76db3051-3dc2-4cbf-9540-264db8bf9168.png)

#### 路由系统的设计

在于现代 MVC 的设计思想，前端框架的设计思想也一直在发生变更，现代 Web 前端框架提供的最经典的能力莫过于将 MVC 中的 Controller 变为了 Router，目前几乎主流的前端框架都支持路由驱动视图，仅提供一个 Router Map 路由表，无需关注控制任何路由状态即可完成跳转后的路由更新。

通过微前端出现的背景和意义，可以了解到微前端主要是用于解决：应用增量升级、多技术体系并存、构建大规模企业级 Web 应用而诞生的。那么在基于 SPA 的微前端架构中也可以了解到，目前微前端主要是采用应用分而治之 + 动态加载 + SPA 应用的模式来解决大规模应用带来的一系列问题。在以组件为颗粒度的 SPA 应用中组件内部是不需要关心路由的，但是在微前端中主要通过应用维度来拆分，那么拆分的应用也可能是一个独立的 SPA 应用，那么此时主应用与子应用的关系如何编排呢？

微前端应用中理想的路由调度，假设存在一个 Garfish 站点，这个站点它是由主应用+三个子应用构成，主应用的 basename 为 /demo，并存在三个 Tab 分别指向跳转至不同的应用，理想的路由效果：

1. 在点击 vue-app Tab，跳转至 /demo/vue-app 路由后，分别激活 vue-app 下，为 Vue 类型的 A 应用和 B 应用，并激活 A 应用和 B 应用中的 Home 组件
2. 点击 React-app Tab 进入到 /demo/react-app 路由后，分别激活 react-app 下，为 React 类型的 C 应用，并激活 C 应用的 Home 组件
3. 在激活 C 应用的基础上，点击 Detail 按钮，跳转至 /demo/react-app/detail，并激活 C 应用的 detail 组件。
4. 点击浏览器返回按钮展示，跳转 /demo/react-app/detail，并激活 C 应用的 Home 组件，至此完成浏览器的基本路由跳转能力。

![image](https://user-images.githubusercontent.com/27547179/165337076-752ff44b-397f-4c02-a755-252e22ae4813.png)

> 不考虑任何路由处理的场景

假设存在一个 Garfish 站点，这个站点它是由主应用+一个子应用构成。由于 Garfish 采用的是 SPA 架构，子应用与主应用所处于同一个执行上下文，子应用的路由原样反应在主应用上。

![image](https://user-images.githubusercontent.com/27547179/165337201-16a88ecb-5a1e-4227-8238-d00799ab34a6.png)

那么此时分别跳转到：/home、/detail 路由会发现哪些问题呢？

- 假定跳转的方法可以同时触发主子应用路由更新，主应用路由和子应用路由会同时发生抢占情况，后渲染的组件会覆盖先渲染的路由组件
- 在触发路由跳转方后，只有主应用视图触发刷新、只有子应用视图刷新、或都不刷新
  - 「视图的路由状态维护在框架内部」，通过原生跳转无法触发视图更新

此时当分别跳转到：/home、/detail、/test 路由时分别触发对应的组件视图，但是倘若子应用路由中也存在 /detail 视图呢，由于应用的开发采用分治的模式，应用的开发从空间和时间上都是分离的，无法保证应用间的路由不发生路由抢占的情况。

「通过 history 路由跳转无法保证应用能够触发视图更新」，在通过 history api 进行路由跳转时，是无法触发应用视图更新，假设存在一个 React 应用 A，存在一个组件视图 Test，分别通过 React 提供的路由方法跳转和原生的路由跳转进行观察：

![image](https://user-images.githubusercontent.com/27547179/165337244-1649b3a5-0048-4bad-a836-247a95c0ceea.png)

Hash 和 History 路由模式
目前主流的 SPA 前端应用基本上都支持两种路由模式，一种是：hash 模式、另一种则是 History 路由模式，两者的优劣和使用并不在本文的讨论范围之内，这里仅做在微前端这种分离式开发模式下的介绍，在微前端这种分离式 SPA 应用开发的模式下该选择哪种路由模式，以及多 SPA 应用下他们的路由应该如何编排：
正常路由情况
假设站点地址为：http://garfish.bytedance.com

- 主应用 history 模式、子应用 history 模式
  - 主应用（basename: /example）：
    - 主应用所有路由基于：http://garfish.bytedance.com/example
    - 例如跳转到：/appA，http://garfish.bytedance.com/example/appA/
  - 子应用（basename: /example/appA）：
    - 子应用所有路由基于：http://garfish.bytedance.com/example/appA
    - 跳转到子应用的 /detail 页，http://garfish.bytedance.com/example/appA/detail
  - 特点：
    - 当主子应用分别为 history 模式时，子应用的路由基于主应用基础路由并带上自己的业务路由
    - 路由同步到主应用路由上，通过 子应用 scope 命名空间隔离（子应用 A，提供 appA 的 scope）主应用和其他应用的路由冲突，并将子应用
    - 路径符合用户和开发者认知和理解
    - 支持嵌套层级使用，并继续通过 scope 的命名空间保证路由可读
- 主应用 history 模式、子应用 hash 模式
  - 主应用（basename: /example）
    - 主应用所有路由基于：http://garfish.bytedance.com/example
    - 例如跳转到：/appA，http://garfish.bytedance.com/example/appA/
  - 子应用（basename: /example/appA）：
    - 子应用所有路由基于：http://garfish.bytedance.com/example/appA
    - 从主应用：http://garfish.bytedance.com/example/appA，跳转到子应用的 /detail 页，http://garfish.bytedance.com/example/appA#/detail
  - 特点：
    - 在一定程度上具备主子应用都为 history 模式的优势，不支持嵌套层级使用
    - 目前多数框架都不支持以 hash 值作为 basename
    - 可读性尚可

异常路由情况

- 主应用 hash 模式、子应用 history 模式
  - 主应用（basename: /example）
    - 主应用所有路由基于：http://garfish.bytedance.com/example
    - 例如跳转到：/detail，http://garfish.bytedance.com/example#/appA
  - 子应用（basename: /example#/appA）：
    - 子应用所有路由基于：http://garfish.bytedance.com/example#/appA
    - 跳转到子应用的 /detail 页，http://garfish.bytedance.com/example/detail#/appA
  - 特点：
    - 「路由混乱」，不符合用户和开发者直觉
    - 目前多数框架都不支持以 hash 值作为 basename
- 主应用 hash 模式、子应用 hash 模式
  - 主应用（basename: /example）
    - 主应用所有路由基于：http://garfish.bytedance.com/example
    - 例如跳转到：/detail，http://garfish.bytedance.com/example#/appA
  - 子应用（basename: /example#/appA）：
    - 子应用所有路由基于：http://garfish.bytedance.com/example#/appA
    - 跳转到子应用的 /detail 页，http://garfish.bytedance.com/example#/detail
  - 特点：
    - 「路由混乱」，不符合用户和开发者直觉
    - 目前多数框架都不支持以 hash 值作为 basename
    - 可能与主应用或其他子应用发生路由冲突

#### Garfish Router 如何处理路由

通过上面理想的路由模式案例发现，微前端应用拆分成子应用后，子应用路由应具备自治能力，可以充分的利用应用解耦后的开发优势，但与之对应的是应用间的路由可能会发生冲突、两种路由模式下可能产生用户难以理解的路由状态、无法激活不同前端框架的下带来的视图无法更新等问题。
目前 Garfish 主要提供了以下四条策略

- 提供 Router Map，减少典型中台应用下的开发者理解成本
- 为不同子应用提供不同的 basename 用于隔离应用间的路由抢占问题
- 路由发生变化时能准确激活并触发应用视图更新

> Router Map 降低开发者理解成本

在典型的中台应用中，通常可以将应用的结构分为两块，一块是菜单另一块则是内容区域，依托于现代前端 Web 应用的设计理念的启发，通过提供路由表来自动化完成子应用的调度，将公共部分作为拆离后的子应用渲染区域。

![image](https://user-images.githubusercontent.com/27547179/165337300-a82aa763-4c70-474f-a33a-dabc7843178b.png)
![image](https://user-images.githubusercontent.com/27547179/165337326-29590a81-4531-47a9-abf7-c1c3b647a2b8.png)

> 自动计算出子应用所需的 basename
> 当应用处于激活状态时，根据应用的激活条件自动计算出应用所需的基础路径，并在渲染时告诉框架，以便于应用间路由不发生冲突。

![image](https://user-images.githubusercontent.com/27547179/165337379-43506a80-71e9-4219-a14d-0f05dd64cfcb.png)

如何有效的触发不同应用间的视图更新
目前主流框架实现路由的方式并不是监听路由变化触发组件更新，让开发者通过框架包装后的 API 进行跳转，并内部维护路由状态，在使用框架提供 API 方法发生路由更新时，内部状态发生变更触发组件更新。
由于框架的路由状态分别维护在各自的内部，那么如何保证在路由发生变化时能及时有效的触发应用的视图更新呢，答案是可以的，目前主要有两种实现策略：

1. 收集框架监听的 popstate 事件
2. 主动触发 popstate 事件
   因为目前支持 SPA 应用的前端框架都会监听浏览器后退事件，在浏览器后退时根据路由状态触发应用视图的更新，那么其实也可以利用这种能力主动触发应用视图的更新，可以通过收集框架的监听事件，也可以触发 popstate 来响应应用的 popstate 事件

## 微前端的优点

- 适用于大规模 Web 应用的开发
- 更快的开发速度
- 支持迭代可开发和增强升级
- 拆解后的部分降低了开发者的理解成本
- 同时具备 UX 和 DX 的开发模式

## 微前端的缺点

- 复杂度从代码转向基础设施
- 整个应用的稳定性和安全性变得更加不可控
- 具备一定的学习和了解成本
- 需要建立全面的微前端周边设施，才能充分发挥其架构的优势
  - 调试工具
  - 监控系统
  - 上层 Web 框架
  - 部署平台

## 何时使用微前端

- 大规模企业级 Web 应用开发
- 跨团队及企业级应用协作开发
- 长期收益高于短期收益
- 不同技术选型的项目
- 内聚的单个产品中部分需要独立发布、灰度等能力
- 微前端的目标并非用于取代 Iframe
  - 应用的来源必须可信
  - 用户体验要求更高

## 总结

微前端概念的出现是前端发展的必然阶段，PC 互联网转向移动互联网时代时，PC 的场景并未完全被消灭，反而转向了衍生出了更多沉浸感更高、体验感更强的应用，与之对应的应该是出现新的架构模式来应对这些应用规模的增长。

微前端也并非银弹，采用微前端后复杂度并未凭空消失，而是由代码转向了基础设施，对架构设计带来了更大的挑战，并且在新的架构下需要设计并提供更多的周边工具和生态来助力这一新的研发模式。

本文更多的是从背景和设计层面讲清楚微前端解决方案应具备哪些能力，以及核心模块的设计。

## 参考资料

- 如何设计微前端中的主子路由调度：https://mp.weixin.qq.com/s/TAXP7ipDdtb2Jb-L3QHszA
- 如何取巧实现一个沙箱：https://mp.weixin.qq.com/s/Mg3fU0WvZUQnlWHdxc-b5A
- 微服务架构及其最重要的 10 个设计模式：https://www.infoq.cn/article/kdw69bdimlx6fsgz1bg3
- single-spa：https://github.com/single-spa/single-spa



---
url: /blog/hmr.md
---

# 热更新问题

> 1. 微前端是为了解决将复杂的单体应用以功能或业务需求垂直的切分成更小的子系统而设计的一套解决方案，主应用和子应用可独立开发、独立部署。微前端模式下主、子应用都是独立的应用，微前端作为运行在主、子应用之下的框架层，不会干涉主、子 应用在 dev 模式下的热更新能力。
> 2. 在微前端场景下，主、子应用的热更新能力需要构建工具层提供相应的配置（例如 webpack）, garfish 不默认提供热更新的能力。
> 3. 但是在微前端场景下，由于应用场景的特殊性，我们也会针对各种场景下的热更新情况作出相应的说明与配置示例，期望能给业务方提供相应的参考。

## 什么是模块热更新？

模块热更新也叫 HMR，全称是 Hot Module Replacement，指当你在更改并保存代码时，构建工具将会重新进行编译打包，并将新的包模块发送至浏览器端，浏览器用新的包模块替换旧的，从而可以在不刷新浏览器的前提下达到修改的功能。

## 模块热更新常用方案

### 配置 webpack 的 hot.module 回调

```js
// webpack.config.js
module.exports = {
  devServer: {
    hot: true,
  },
}

// index.tsx
import ReactDOM from 'react-dom';
import App from './components/App';

// 设置 hot.module 回调开启热更新：
if ((module as any).hot) {
  (module as any).hot.accept(['./components/App'], () => {
    ReactDOM.render(<App />, document.getElementById('root'));
  });
}
```

### react-fast-refresh 插件

> React 官方提供，相比于 react-hot-loader，容错能力更高。

```js
// webpack.config.js
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
const isDevelopment = process.env.NODE_ENV !== 'production';
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: './index.js',
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        loader: 'babel-loader',
        options: {
          presets: ['@babel/env', '@babel/preset-react'],
          plugins: [require.resolve('react-refresh/babel')], // 为 react-refresh 添加
        },
      },
    ],
  },
  plugins: [
    isDevelopment && new ReactRefreshPlugin(), // 为 react-refresh 添加
    new HtmlWebpackPlugin({
      template: './index.html',
    }),
  ],
};
```

### react-hot-loader 插件

1. react-hot-loader 对代码侵入性较大，需要使用 `hot` 包裹入口组件。
2. 其次，如果使用 ts-loader（没有使用 babel-loader） 去编译 ts 文件的话，使用 react-hot-loader 会不成功，因为 react-hot-loader 依赖于 babel-loader，所以对于使用 ts-loader 的项目来说不太友好。

> React-Hot-Loader is expected to be replaced by React Fast Refresh. Please remove React-Hot-Loader if Fast Refresh is currently supported on your environment -- 官网

```js
// webpack.config.js
module.exports = {
// 1. 在入口添加 react-hot-loader/patch, 保证 react-hot-loader 在 react 和 react-dom 之前加载
  entry: ['react-hot-loader/patch', './src'],
  ...
  // 2. 设置 ts/tsx 的编译方式，使用 babel-loader 时在 options 中添加 plugins
   {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        use: {
          loader: "babel-loader",
          options: {
            cacheDirectory: true,
            babelrc: false,
            presets: [
              [
                "@babel/preset-env",
              ],
              "@babel/preset-typescript",
              "@babel/preset-react",
            ],
            plugins: [
              // plugin-proposal-decorators is only needed if you're using experimental decorators in TypeScript
              ["@babel/plugin-proposal-decorators", { legacy: true }],
              ["@babel/plugin-proposal-class-properties", { loose: true }],
              "react-hot-loader/babel", // 添加 react-hot-loader 插件
            ],
          },
        },
   }
   // ... other configuration options
   resolve: {
    // 3. 设置 @hot-loader/react-dom，支持 React Hooks
    alias: {
      "react-dom": "@hot-loader/react-dom",
    },
  },};

// App.js
import { hot } from 'react-hot-loader/root';
const App = () => <div>Hello World!</div>;
export default hot(App);
```

## 微前端不同场景下热更新表现

首先，请确认微前端应用的构建配置已按照推荐配置进行了设置：

```js
// webpack.config.js
module.exports = {
  output: {
    // 开发环境设置 true 将会导致热更新失效
    clean: process.env.NODE_ENV === 'production' ? true : false,
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    jsonpFunction: 'garfish-demo-react17',
    // 保证子应用的资源路径变为绝对路径
    publicPath: 'http://localhost:8080',
  },
};
```

### 主、子 应用都在本地

- 支持主应用热更新；
- 支持子应用热更新；

### 主应用线上、子应用线下

- 子应用独立启动时，子应用热更新能力不受影响；
- 在微前端模式下的子应用（即主应用线上加载的线下子应用）
  - 【若当前域名为子应用域名】：子应用 hmr 能力不受影响；
  - 【若当前域名为主应用域名】：需要指定 ws 的连接地址为本地 ws 连接

```js
// 以 webpack 为例，可以通过 devServer 的 client.webSocketURL 来指定 ws 地址
// 值得注意的是，当本地地址指定为 0.0.0.0 时，ws 指定为本地并未生效, 即依然为ws的默认连接地址(当前域名)
// 可以指定本地地址 localhost 或者 127.0.0.1 ，请保证该 ws 连接有效

module.exports = {
  devServer: {
    hot: true,
    open: true,
    historyApiFallback: true,
    port,
    headers: {
      'Access-Control-Allow-Origin': '*',
    },
    allowedHosts: 'all',
    // 配置 webSocketURL 地址为本地 ws, 达到微前端模式下子应用热更新的能力
    client: {
      webSocketURL: 'ws://localhost:8091/ws', // ok
      // webSocketURL: 'ws://127.0.0.1:8091/ws', // ok
      // webSocketURL: 'ws://0.0.0.0:8091/ws', // wrong

      // webSocketURL: {
      //   hostname: 'localhost', // ok
      //   hostname: '127.0.0.1', // ok
      //   hostname: '0.0.0.0',  // wrong
      //   pathname: '/ws',
      //   password: 'dev-server',
      //   port: 8091,
      //   protocol: 'ws',
      //   username: 'webpack',
      // },
    },
  },
};
```

## 常见问题

### 子应用热更新未生效

主应用线下、子应用线下场景：

- 首先检查子应用作为独立应用启动时，是否具备热更新能力。
  - 如果子应用运行没有 HMR 能力，需要排查问题
    - 若使用了 react-fast-refresh。webpack 的  externals  配置项会导致  react-refresh  失效，可在  dev 环境下可以先关闭配置。
    - 若使用了 react-fast-refresh。react-refresh 最低支持版本  react-dom@16.9+，如果热更新没有生效，请确认版本是否满足要求。
    -
- 如果子应用作为独立应用启动时，具备热更新能力，但微前端模式下未生效，可能原因：

  - 若主应用使用了 react-fast-refresh webpack 插件作为热更新配置，请关闭该配置：

    ```js
    // webpack 场景，禁用 react-fast-refresh ，可改用 webpack hot.module 回调
    // 或使用 react-hot-loader
    plugins: [
        // 微前端场景下子应用热更新需要关闭 react-fast-refresh, 否则子应用热更新不会生效
        // isDevelopment && new ReactRefreshWebpackPlugin()
      ],
    ```

    - 禁用 react-fast-refresh 后，根组件可使用 webpack hot.module 回调，达到热更新效果

    ```js
    // 根组件使用 webpack hot.module 回调，达到热更新效果
    // index.tsx
    import ReactDOM from 'react-dom';
    import App from './components/App';

    // 设置 hot.module 回调开启热更新：
    if ((module as any).hot) {
      (module as any).hot.accept(['./components/App'], () => {
        ReactDOM.render(<App />, document.getElementById('root'));
      });
    };
    ```

    - 禁用 react-fast-refresh，也可以使用 react-hot-loader ，达到热更新效果

    ```js
    // App.tsx
    import { hot } from 'react-hot-loader';
    const RootComponent = () => {
        ...
    }
    export default hot(module)(RootComponent);

    // index.tsx
    import ReactDOM from 'react-dom';
    import App from './components/App';

    // 设置 hot.module 回调开启热更新：
    if ((module as any).hot) {
      (module as any).hot.accept(['./components/App'], () => {
        ReactDOM.render(<App />, document.getElementById('root'));
      });
    };
    ```

主应用线上、子应用线下场景：

- 【若在主应用域名下】

  - 观察子应用 ws 连接是否正常，若 ws 连接失败需要指定 ws 地址为本地 ws 地址；

- 【若在子应用域名下】
  - 正常情况下子应用的 hmr 能力应不受影响。若出现 ws 连接正常，资源请求正常，页面未正确更新。若使用的是 react-fast-refresh 插件，请确认项目中该插件仅注册了一次（一般情况下我们一次性也需要跑一个 dev 的应用），原因是 react-refresh 中存在防重复注入机制，若加载多次，新的 webpack runtime 中 劫持 **REACT_DEVTOOLS_GLOBAL_HOOK** 相关的代码并不会再次被执行。当代码变更 webpack 进行热更新时，因为闭包的原因，mountedRootsSnapshot 这个变量寻找的是之后加载的 runtime 里定义的模块里的变量，长度为 0，直接跳过更新阶段。这也是主、子应用均为 dev 模式下子应用若需要热更新，那么主应用需要关闭 react-fast-refresh 的原因。

```js
/* global __react_refresh_library__ */

const safeThis = require('core-js-pure/features/global-this');
const RefreshRuntime = require('react-refresh/runtime');

if (process.env.NODE_ENV !== 'production') {
  if (typeof safeThis !== 'undefined') {
    var $RefreshInjected$ = '__reactRefreshInjected';
    // Namespace the injected flag (if necessary) for monorepo compatibility
    if (
      typeof __react_refresh_library__ !== 'undefined' &&
      __react_refresh_library__
    ) {
      $RefreshInjected$ += '_' + __react_refresh_library__;
    }

    // Only inject the runtime if it hasn't been injected
    if (!safeThis[$RefreshInjected$]) {
      // Inject refresh runtime into global scope
      RefreshRuntime.injectIntoGlobalHook(safeThis);

      // Mark the runtime as injected to prevent double-injection
      safeThis[$RefreshInjected$] = true;
    }
  }
}
```

### 主应用热更新后子应用内容丢失

这种情况发生在主、子 应用都为本地的场景下。在子应用页面下主应用热更新后子应用内容丢失。
此问题 garfish 方案已解决。请升级 garfish 至最新版本。



---
url: /blog/sourcemap.md
---

# 错误处理和 sourcemap

## 背景

微前端场景下，存在沙盒机制，基于 eval 和 new Function 的形式去实现沙箱机制。在手动执行代码的情况下，会产生堆栈丢失、sourcemap 还原错行等问题。

## 解决方案

1. 修改代码执行方式，开发环境可用

> 解决堆栈错行

- step1：升级主应用至 garfish 至最新版本

2. 新增 webpack 插件，解决生产环境问题堆栈还原问题

> 子应用与 Garfish 相关微前端配置可以自动生成，解决代码压缩后在 Garfish 沙箱内执行堆栈异常

```js
// webpack配置
const webpack = require('webpack');

config.plugins = [
  new webpack.BannerPlugin({
      banner: 'Micro front-end',
  });
]
```

## 具体问题

## 堆栈丢失问题

使用 eval、new Function 去执行函数，如果在错误抛出的时候，堆栈是不完整的，只会显示到 eval 或 new Function 执行的那行。
如

```js
var str = `
    var a = 1;
    throw Error(123)
`;
eval(str);
```

错误抛出的位置是 eval 的这行，（new Function 同理）。
![image.png](https://tosv.byted.org/obj/eden-internal/ozpmyhn_lm_hymuPild/ljhwZthlaukjlkulzlp/sourcemap1.png)

这也是此前许多使用 Garfish 的用户遇到的一个问题，js 执行出错，但是缺少堆栈，导致排查困难。

## 解决方法

对于此问题，浏览器是提供了相关解决方案来解决的，那就是 sourceURL。
（ MDN：https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Debug_eval_sources ）

我们还是拿上面的例子，增加了 sourceURL

```js
var str = `
    var a = 1;
    throw Error(123)
//# sourceURL=./index.js
`;
eval(str);
```

可以看到有了具体的堆栈。

于是 Garfish 执行代码的形式变成，这样抛出的错误就有详细的堆栈，能够解决看不到堆栈的问题。

```js
new Function('
    ...code
//# sourceURL=url
'
```

## sourcemap 对应错误

### 错行

由于使用 new Function 来执行，加上拼接了一些变量，所以使用构建生成的 sourcemap 来还原会导致错行的问题。
源码

```js
// code

// 沙箱里执行的代码
function (window) {
    with(window) {
        // code
    }
}
```

可以看到使用 sourcemap 还原的时候会错两行，这也是很多使用 Garfish 的同学遇到的问题，sourcemap 定位错误，虽然能够还原一定的情况，但是对于 debug 来说，还是比较蛋疼的。

#### 解决方法

使用 eval 替代 new Function，同时将拼接的代码放置于同一行。

形如

```js
eval(function(window) {{with} { //code
}}
```

这样可以解决错行的问题。

### 错列

上面的解决方法可以解决行数对应不上的问题，在开发环境基本没有问题，因为代码没有进行压缩。
由于在前面增加了"function(window)"，列数对应还是有问题的，特别是对于生产环境还是有比较大的问题，因为生产环境代码会压缩成一行，所以列数对应不上就成了大问题。

### 方案对比

1. 在运行时进行错误抛出的时候修正列数
   我们可以计算出错的列数的数字，catch 住错误然后对 error 的 stack 进行修改。
   问题：无法捕获所有的错误，有的错误不是在编译阶段抛出，可能在页面渲染或者交互的时候抛出的，这些错误 garfish 无法捕获，也尝试重写 Error 对象，但是无法涵盖全部情况。

- 捕获所有异常
  - window.onerror
  - 常见异步 api 封装：
    - setTimeout、promise 捕获异常
  - Dom
    - 事件流都包了一层

2. 在编译的时候修正列数
3. 在编译阶段修正，如生成的 sourcemap 就进行列的偏移，但是这会导致独立运行的时候子应用堆栈不正确。
   所以经过考虑，可能在生产编译产物和 sourcemap 的时候，就默认给 js 文件顶部生产一行注释，不仅可以解决行数列数对应不上问题，也可以解决独立运行子应用的问题。对于不经过编译的 cdn 加载文件有问题。



---
url: /issues/webComponent.md
---


本节主要从主应用视角出发，通过 `Web Component` 概览性描微前端应用，Web Component 接入方式特点：

- 便于与主应用框架结合使用，加载微前端应用像加载组件一样简单
- 支持设置子应用 Loading 中间态、错误态占位内容
- 可以与路由驱动模式一起使用

## 主应用

### 安装依赖

```bash npm2yarn
npm install garfish --save
```

### 入口处注册 Web Component

```js
// index.js（主应用入口处）
import { defineCustomElements } from 'garfish';

// 定义 WebComponent Tag 为“micro-portal”，并指定 loading 时的内容
defineCustomElements('micro-portal', {
  loading: ({ isLoading, error, pastDelay }) => {
    let loadingElement = document.createElement('div');
    // 渲染过程中发生异常，展示异常内容
    if (error) {
      loadingElement.innerHTML = `load app get error: ${error.message}`;
      return loadingElement;
    }
    // 渲染中，并且符合延迟时间（避免 loading 闪退）
    if (pastDelay && isLoading) {
      loadingElement.innerHTML = `loading`;
      return loadingElement;
    }
    return null;
  },
});
```

### 分配路由给微前端应用

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="framework">
  <TabItem value="React" label="React" default>

```jsx
import React from 'react';
import { BrowserRouter, Route, Link, Switch } from 'react-router-dom';

function VueApp(basename) {
  // name: 子应用名称
  // entry: 子应用入口资源地址，可以为 HTML、或 JS
  // basename: 子应用路由的基础路径
  return (
    <micro-portal
      name="vue-app"
      entry="http://localhost:8092"
      basename={basename}
    ></micro-portal>
  );
}

function App() {
  return (
    <BrowserRouter basename={'/'}>
      <Link to="/vue-app">VueApp</Link>
      <Switch>
        // 分配一个路由给 vue 应用
        <Route path="/vue-app" component={() => VueApp('/vue-app')}></Route>
      </Switch>
    </BrowserRouter>
  );
}
```

  </TabItem>
  <TabItem value="Vue" label="Vue">

> 提供 ReactApp 的 Vue 组件

```html
<!-- ./component/ReactApp.vue -->
<template>
  <div>
    <micro-portal
      name="react-app"
      entry="http://localhost:8093"
      basename="/react-app"
    />
  </div>
</template>

<script>
  export default {
    name: 'App',
  };
</script>
<style></style>
```

> 将 ReactApp 组件添加到路由中

```js
// index.js
import Vue from 'vue';
import VueRouter from 'vue-router';
import ReactApp from './component/ReactApp.vue';

const router = new VueRouter({
  mode: 'history',
  base: '/',
  routers: [{ path: '/react-app', component: ReactApp }],
});

new Vue({
  router,
  store,
  render: (h) => h(App),
}).$mount('#app');
```

  </TabItem>
</Tabs>

## 子应用

### 安装依赖

```bash npm2yarn
npm install @garfish/bridge-react --save
```

### 通过 Bridge 函数包装子应用

<Tabs groupId="framework">
  <TabItem value="React" label="React" default>

```jsx
import { BrowserRouter, Switch, Route, Link } from 'react-router-dom';
import { reactBridge } from '@garfish/bridge-react';

function App({ basename }) {
  return (
    // 根组件使用传递过来的 basename，作为应用的基础路径
    <BrowserRouter basename={basename}>
      <Link to="/">Home</Link>
      <Switch>
        <Route exact path="/">
          <HelloGarfish />
        </Route>
      </Switch>
    </BrowserRouter>
  );
}

export const provider = reactBridge({
  rootComponent: App,
  domElementGetter: '#root', // 应用的挂载点，如果子应用打包为 JS 入口，可不填写
});
```

  </TabItem>
  <TabItem value="Vue" label="Vue">

```js
import App from './App.vue';
import { vueBridge } from '@garfish/bridge-vue-v2';

function newRouter(basename) {
  const router = new VueRouter({
    router,
    mode: 'history',
    base: basename,
    routes: [{ path: '/', component: HelloGarfish }],
  });
  return router;
}

export const provider = vueBridge({
  rootComponent: App,
  appOptions: ({ basename }) => {
    const router = newRouter(basename);
    return {
      store,
      router,
      el: '#app',
    };
  },
});
```

  </TabItem>
</Tabs>

### 调整子应用的构建配置

<Tabs>
  <TabItem value="Webpack" label="Webpack" default>

```js
// webpack.config.js
const webpack = require('webpack');

module.exports = {
  output: {
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // 请求确保每个子应用该值都不相同，否则可能出现 webpack chunk 互相影响的可能
    jsonpFunction: 'vue-app-jsonpFunction',
    // 保证子应用的资源路径变为绝对路径，避免子应用的相对资源在变为主应用上的相对资源，因为子应用和主应用在同一个文档流，相对路径是相对于主应用而言的
    publicPath: 'http://localhost:8000',
  },
  plugin: [
    // 保证错误堆栈信息及 sourcemap 行列信息正确
    new webpack.BannerPlugin({
      banner: 'Micro front-end',
    })
  ],
  devServer: {
    // 保证在开发模式下应用端口不一样
    port: '8000',
    headers: {
      // 保证子应用的资源支持跨域，在线上后需要保证子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）
      'Access-Control-Allow-Origin': '*',
    },
  },
};
```

  </TabItem>
</Tabs>



---
url: /issues/index.md
---

# 常见问题



## "provider" is "null".

出现这个问题是因为 garfish 无法从子应用中正确获取到 `provider` 导出函数，可以先按照以下步骤自查：

1. 检查子应用是否正确 export 了 provider 函数。[参考](/guide/quick-start/start.md#2导出-provider-函数)
2. 检查子应用是否正确配置了 webpack 的 output 配置：

```js
// webpack.config.js
const webpack = require('webpack');
const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  output: {
    // 开发环境设置 true 将会导致热更新失效
    clean: isDevelopment ? false : true,
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].js',
    // 需要配置成 umd 规范
    libraryTarget: 'umd',
    // 修改不规范的代码格式，避免逃逸沙箱
    globalObject: 'window',
    // webpack5 使用 chunkLoadingGlobal 代替，或不填保证 package.json name 唯一即可
    jsonpFunction: 'garfish-demo-react',
    // 保证子应用的资源路径变为绝对路径
    publicPath: 'http://localhost:8080',
  },
  plugin: [
    // 保证错误堆栈信息及 sourcemap 行列信息正确
    new webpack.BannerPlugin({
      banner: 'Micro front-end',
    }),
  ],
  devServer: {
    // 保证在开发模式下应用端口不一样
    port: '8000',
    headers: {
      // 保证子应用的资源支持跨域，在上线后需要保证子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）
      'Access-Control-Allow-Origin': '*',
    },
  },
};
```

【重要】注意：

1. libraryTarget 需要配置成 umd 规范；
2. globalObject 需要设置为 'window'，以避免由于不规范的代码格式导致的逃逸沙箱；
3. 如果你的 webpack 为 v4 版本，需要设置 jsonpFunction 并保证该值唯一（否则可能出现 webpack chunk 互相影响的可能）。若为 webpack5 将会直接使用 package.json name 作为唯一值，请确保应用间的 name 各不相同；
4. publicPath 设置为子应用资源的绝对地址，避免由于子应用的相对资源导致资源变为了主应用上的相对资源。这是因为主、子应用处于同一个文档流中，相对路径是相对于主应用而言的
5. 'Access-Control-Allow-Origin': '\*' 允许开发环境跨域，保证子应用的资源支持跨域。另外也需要保证在上线后子应用的资源在主应用的环境中加载不会存在跨域问题（**也需要限制范围注意安全问题**）；

3) 确认子应用 `entry` 地址设置正确：若为 html 的入口类型 `entry` 配置为 html 入口地址，若为 js 类型，子应用 `entry` 配置为 js 入口地址；

4) 若子应用为 js 入口，需要保证子应用的资源被打包成了单 bundle，若有部分依赖未被打包成 bundle 会导致子应用无法正常加载。例如子应用使用了 webpack splitChunk 进行拆包且为 js 入口时，会导致上述报错；

5) 如以上途径都无法解决，请试图通过环境变量导出，这将会让 Garfish 框架更准确的获取到导出内容：

```js
if (window.__GARFISH__ && typeof __GARFISH_EXPORTS__ !== 'undefined') {
  // eslint-disable-next-line no-undef
  __GARFISH_EXPORTS__.provider = provider;
}
```

## 微应用 JSONP 跨域错误怎么处理？

在使用 Garfish 时，微应用的动态脚本（如 JSONP）会被转化为 fetch 请求，这要求后端服务支持跨域请求，否则会产生错误。

可以使用 [excludeAssetFilter](/api/registerApp.md#sandbox) 参数来放行这些资源请求，但请注意，被该参数放行的资源会逃逸出沙箱，可能导致副作用，需自行处理。

## Uncaught (in promise) TypeError: \[Garfish warning]: Cannot read properties of undefined (reading 'call')

* 错误原因

  * 这个问题出现在子应用构建为 umd 格式后存在脚本出现了 `type="module"` 的标识，这将导致该 script 逃逸出沙箱执行，而其余脚本在沙箱内执行，找不到 chunk 导致报错。

* 解决方案
  * 请确保子应用构建为 umd 格式后 script 不会带上 `type="module"` 标识，保证子应用的正常解析和渲染。

## Invalid domGetter "xxx"

错误原因：在 Garfish 开始渲染时，无法查询到该挂载节点则会提示该错误

> 解决方案

1. 将挂载点设置为常驻挂载点，不要跟随路由变化使子应用挂载点销毁和出现
2. 保证 Garfish 在渲染时挂载点存在

## 如何获取主应用的 localStorage

可按照如下配置获取主应用的 localStorage：

```ts
import Garfish from 'garfish';

Garfish.run({
  ...,
  sandbox: {
    modules: [
      () => ({
        override: {
          localStorage: window.localStorage,
        },
      }),
    ],
  }
});
```

类似 localStorage，子应用若需要获取被沙箱隔离机制隔离的全局变量上的变量，均可通过上述方式获取。

## 如何判断子应用是否微前端应用中

可通过环境变量 `window.__GARFISH__` 判断。

## 如何手动挂载子应用

可通过 [Garfish.loadApp](/api/loadApp.md) 动态加载子应用。

## HTML entry 和 JS entry 差异

* HTML entry

  * 指的是子应用配置的资源地址是 HTML 的地址
  * 指定子应用的 entry 地址为 HTML 地址，支持像 iframe 一样的能力，将对应的子应用渲染至当前应用中
  * HTML entry 模式的作用设计的初衷，解决子应用：**独立开发**、**独立测试** 的能力

* JS entry

  * 指的是子应用配置的资源地址就是一个 JS 地址

* 二者在使用层面上的差异
  * 在作为 `html entry` 时，子应用的挂载点需要基于传入的 `dom` 节点进行选中挂载点
  * 因为在 `html entry` 时，其实类似于 `iframe` 的模式，子应用在独立运行时的所有 `dom` 结构都会被挂到主应用的文档流上（整个文档流会挂载在当前 html 上）
  * 所以子应用在渲染时需要根据子应用的 `dom` 结构去找他的挂载点。

- HTML entry 正确渲染销毁写法

```js {6}
export const provider = () => {
  return {
    render({ dom }) {
      ReactDOM.render(
        React.createElement(HotApp),
        dom.querySelector('#root'), // 基于 dom 去选中文档流中的 #root，就和在独立运行时使用 document.querySelector('#root') 一样
      );
    },
    destroy({ dom }) {
      // 此外，destroy 应该正确的执行
      const root = dom && dom.querySelector('#root');
      if (root) {
        ReactDOM.unmountComponentAtNode(root);
      }
    },
  };
};
```

* JS entry 正确渲染销毁写法

```js
export const provider = ({ dom, basename }) => ({
  render() {
    ReactDOM.render(<App basename={basename} />, dom); // 作为 js entry 时，没有自己的文档流，只有提供的渲染节点
  },

  destroy({ dom }) {
    ReactDOM.unmountComponentAtNode(dom); // 没有自己的文档流，直接销毁
  },
});
```

## garfish 支持多实例吗

支持。

目前 garfish 支持多实例场景，业务使用场景可分为 「非嵌套场景」 和 「嵌套场景」：

* 非嵌套场景下

- 非嵌套场景下，子应用请勿在安装引入 Garfish 包，并导入使用。
- 子应用如果想要在微前端场景下使用 Garfish 包的相关能力，可判断在微前端环境内时，通过 `window.Garfish` 使用相关接口。

```js
if (window.__GARFISH__) {
  window.Garfish.xx;
}
```

* 嵌套场景

- Garfish 目前内部的设计都支持嵌套场景，如果业务对这一块有诉求可以使用，协助我们一起推进在嵌套场景下的能力。

## 子应用销毁后重定向逻辑影响其他子应用

可能原因，出现该问题的原因是子应用未正常销毁，当子应用未正常销毁时，其路由监听事件也未跟随子应用的销毁而销毁

> React 应用解决方案

* 需要保证渲染的节点和销毁的节点为同一个节点，否则导致 React 组件销毁不正常，[ReactDOM.unmountComponentAtNode API 使用说明](https://reactjs.org/docs/react-dom.html#unmountcomponentatnode)
* 这里需要注意的是子应用的入口类型，如果子应用是构建为 js 入口时，则不存在 html 模板，可以直接将 dom 作为挂载点。但也需要保证渲染和销毁的为同一个节点

```js
export const provider = () => {
  return {
    render: ({ dom, basename }) => {
      const root = dom ? dom.querySelector('#root') : document.querySelector('#root');
      ReactDOM.render(
        <React.StrictMode>
          <App basename={basename} />
        </React.StrictMode>,
        root,
      );
    },

    destroy: ({ dom, basename }) =>{
      const root = dom ? dom.querySelector('#root') : document.querySelector('#root');
      ReactDOM.unmountComponentAtNode(root),
    },
  };
};
```

## You are attempting to use a basename on a page whose URL path does not begin with the basename.

> 问题原因

* 出现这个错误的原因一般是因为子应用没有正确的设置子应用的 basename 所导致的。
* 子应用的 `basename` = 主应用的 `basename` + 子应用设置的激活路径 `activeWhen`，这个值会在生命周期函数中由 garfish 默认通过通过参数传递过来，直接使用即可。

> 解决方案

* 将生命周期函数中主应用传递过来的 `basename` 设置为子应用的 `basename`。[参考](/guide/demo/react.md#3-根组件设置路由的-basename)

## 刷新直接返回子应用内容

> 问题原因

* 微前端是一个 SPA 应用，加载子应用是通过 SPA 模式来动态的加载其他子应用内容
* 当访问到主应用的某个路径下激活子应用时是不存在这个路径下的静态资源的，从而 failback 到主应用的内容
* Garfish 在初始化时根据当前路径来确定加载的子应用
* 如果在访问主应用的某个路径时来加载子应用，而这个地址已经存在一个静态资源，浏览器将会直接返回该资源

> 解决方案

* 子应用的资源地址不要和主应用上面激活路径的资源地址一致

## 子应用的接口和资源路径不正确

尽可能将子应用的接口请求和资源路径调整为绝对路径

1. 子应用在独立运行时，使用相对路径的接口，接口请求的路径是，当前页面域名+相对路径
2. 但是在主应用时，子应用使用相对路径的接口，请求的路径按道理来说还是，当前域名+相对路径

当在微前端的场景下如果 Garfish 让子应用走「当前域名+相对路径」会发生更多的异常请求（hmr 热更新、websock、server worker ...），因为子应用的域名并不一定是与主应用一致，因此 Garfish 框架会对相对路径的资源和请求去进行修正，修正的参照物为基础域名为子应用的路径，在本地开发时可能是正常的，但是发到线上出现问题，原因在于发布到线上之后，Goofy web 为了提升子应用资源加载的性能，子应用的入口会走 CDN。因此参照的基础路径就变为了 CDN 前缀。那么此时子应用的相对路径请求就变为了 CDN 前缀。这一块做了很多权衡，因为 hmr、websock、server worker 这些内容可能难以被用户控制，所以默认走的还是修正模式。

## 为什么主应用仅支持 history 模式？

* 目前 Garfish 是通过命名空间去避免应用间的路由发生冲突的。

* 主应用仅支持 `history` 模式的原因在于，`hash` 路由无法作为子应用的基础路由，从而可能导致主应用和子应用发生路由冲突。

## 根路由作为子应用的激活条件？

* 有部分业务想将根路径作为子应用的激活条件，例如 `garfish.bytedance.com` 就触发子应用的渲染，由于目前子应用 **字符串的激活条件为最短匹配原则**，若子应用 `activeWhen: '/'` 表明 `'/xxx'` 都会激活。

* 之所以为最短匹配原则的原因在于，我们需要判断是否某个子应用的子路由被激活，如果可能是某个子应用的子路由，我们则可能激活该应用。

* 之所以有该限制是由于若某个子应用的激活条件为 `/`，则该应用的 `/xx` 都可能为改子应用的子路由，则可能与其他应用产生冲突，造成混乱。

## 子应用拿到 basename 的作用？

为什么推荐子应用拿通过 `provider` 传递过来的 `basename` 作为子应用的 `basename`，有些业务方在实际过程中直接通过约定形式直接在子应用增加 `basename` 已到达隔离的效果，但该使用方式可能导致主应用如果变更 `basename` 可能导致子应用无法一起变更生效。

例如：

1. 当前主应用访问到 `garfish.bytedance.com` 即可访问到该站点的主页，当前 `basename` 为 `/`，子应用 vue，访问路径为 `garfish.bytedance.com/vue`

2. 如果主应用想更改 `basename` 为 `/site`，则主应用的访问路径变为`garfish.bytedance.com/site`，子应用 vue 的访问路径变为 `garfish.bytedance.com/site/vue`

3. 所以推荐子应用直接将 `provider` 中传递的 `basename` 作为自身应用的基础路由，以保证主应用在变更路由之后，子应用的相对路径还是符合整体变化

> 微前端场景下，每个子应用可能都有自己的路由场景，为保证子应用间路由不冲突，Garfish 框架将配置的 `basename` + `子应用的 activeWhen` 匹配的路径作为子应用的基路径。

* 若在 Garfish 上配置 `basename: /demo`，子应用的激活路径为：`/vue2`，则子应用得到的激活路径为：`/demo/vue2`
* 若子应用的激活条件为函数，在每次发生路由变化时会通过校验子应用的激活函数若函数返回 `true` 表明符合当前激活条件将触发路由激活，
* Garfish 会将当前的路径传入激活函数分割以得到子应用的最长激活路径，并将 `basename` + `子应用最长激活路径传` 给子应用参数
* **子应用如果本身具备路由，在微前端的场景下，必须把 basename 作为子应用的基础路径，没有基础路由，子应用的路由可能与主应用和其他应用发生冲突**

## 子应用使用 style-component 切换子应用后样式丢失

* 开启 Style-component 后在生产模式下 style 将会插入到 sheet 中（[React Styled Components stripped out from production build](https://stackoverflow.com/questions/53486470/react-styled-components-stripped-out-from-production-build)）
* 应用重渲染后 style 重新插入后依然，但是 sheet 未恢复

解决方案在使用 `style-component` 的子应用添加环境变量：`REACT_APP_SC_DISABLE_SPEEDY=true`

### arco-design 多版本样式冲突

1. [Arco-design 全局配置 ConfigProvider](https://arco.design/react/components/config-provider)
2. 给子应用分别设置不同的 `prefixCls` 前缀

### ant-design 样式冲突

1. 配置 `webpack` 配置

```js
module.exports = {
  module: {
    rules: [
      {
        test: /\.less$/i,
        use: [
          { loader: 'style-loader' },
          { loader: 'css-loader' },
          {
            loader: 'less-loader',
            options: {
              modifyVars: {
                '@ant-prefix': 'define-prefix', // 定制自己的前缀
              },
              javascriptEnabled: true,
            },
          },
        ],
      },
    ],
  },
};
```

2. 配置公共前缀：[antdesign-config](https://ant.design/components/config-provider/#API)

```js
import { ConfigProvider } from 'antd';

export default () => (
  <ConfigProvider prefixCls="define-prefix">
    <App />
  </ConfigProvider>
);
```

## 子应用热更新问题

garfish 子应用热更新问题请参考 [博客](/blog/hmr.md)

## 如何独立运行子应用

通过 `window.__GARFISH__` 可判断当前子应用是否处于微前端下，通过此变量判断何时独立运行子应用：

```js
// src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom';
import App from './components/App';

// 这能够让子应用独立运行起来，以保证后续子应用能脱离主应用独立运行，方便调试、开发
if (!window.__GARFISH__) {
  ReactDOM.render(<App />, document.querySelector('#root'));
}
```

## 已有 `SPA` 应用如何改造为 garfish 子应用

### 场景描述

* 很多需要改造成微前端的 `SPA` 应用，都是已经存在的旧应用。
* 可能需要逐步拆解应用内的部分路由，变为子应用。
* 主应用现有路由如何与微前端路由驱动共存，是迁移过程中常遇到的。

### 如何逐步改造（以 `react` 为例）

1. 增加 `id` 为 `micro-app` 的挂载点，预留给子应用挂载，`Router` 部分的内容为主应用其他路由。
2. 主应用增加匹配到子应用路由前缀时，`Router` 内容为空。
3. 配置子应用列表时以 `Router` 内容为空时的前缀作为子应用激活条件前缀。

主应用的根组件：

```jsx
<BrowserRouter getUserConfirmation={getConfirmation}>
  <RootContext.Provider value={provider}>
    <Header />
    <div className="container">
      <Router routes={routes} />
      <div id="micro-app" />
    </div>
  </RootContext.Provider>
</BrowserRouter>
```

routes：

```js
export default [
  {
    path: '/platform/search',
    component: Search,
  },
  {
    // 以 /platform/micro-app 开头的应用Router都不展示内容
    path: '/platform/micro-app',
    component: function () {
      return null;
    },
  },
  {
    component: Home,
  },
];
```

主入口处：

```js
Garfish.run({
  domGetter: '#micro-app',
  basename: '/platform/micro-app',
  apps: [
    ...
  ],
});
```

## 子应用动态插入到 body 上的节点逃逸？

* 首先 garfish 会对每一个子应用创建一个 app container 用于包裹子应用，会创建 `__garfishmockhtml__`、 `__garfishmockbody__` 等 mock 节点。
* 对于在子应用运行过程中动态添加到 body 上的节点（如 drawer 组件），garfish 并未
  将此类节点移动到 mock 的 `__garfishmockbody__` 中，原因是有些组件库会计算在 dom 层级中的位置，所以目前 garfish 会主动让其逃逸到上层。
* 在子应用运行过程中动态添加到 body 上的节点在子应用卸载时，garfish 并不会默认回收其 DOM 副作用，需要用户主动在组件的销毁回调里触发 dom 的回收，防止 DOM 副作用未销毁带来的影响。

## 子应用 addEventListener 注册的事件监听在子应用卸载后并未销毁

* 若子应用默认开启了缓存模式，在子应用卸载时会保留应用的上下文，不会默认清除 addEventListener 注册的事件监听，这是因为再次渲染该子应用时 garfish 只会执行 render 函数，因此子应用的副作用不会随意被清除。

* 这种情况建议用户在组件的销毁函数里面手动释放组件的副作用，若有些逻辑确实需要清除，并且需要保证应用可用性可以将 cache 设置成 false。

## garfish 缓存模式

* garfish 目前默认启用了缓存模式，在缓存模式下 garfish 会保留应用的上下文，且不会重新执行所有代码，只会执行 render 和 destory 函数，因此应用的性能将得到很大的提升。

* 在缓存模式下 garfish 只会隔离环境变量和样式，子应用卸载时会保留应用的上下文，不会默认清除子应用的副作用。若业务存在需要销毁的副作用，一般来说建议用户在组件的销毁函数里面手动释放组件的副作用，如果有些逻辑确实需要清除，并且需要保证应用可用性可以把 cache 设置成 false。

## JS 错误上报 Script error 0

* 一般错误收集的工具都是通过：
  * `window.addEventListener('error', (...args) => { console.log(args) })`
  * `window.addEventListener('unhandledrejection', (...args) => { console.log(args) })`
* 如果能打印出 error 对象，但是只能拿到类似 Script error 0. 这类信息。说明当前 js error 跨域了【由于浏览器跨域的限制，非同域下的脚本执行抛错，捕获异常的时候，不能拿到详细的异常信息，只能拿到类似 Script error 0. 这类信息】。通常跨域的异常信息会被忽略，不会上报。可以通过一下方法验证是否跨域（如果输出 Script error 0. 则为跨域）

> 解决方案

由于浏览器跨域的限制，非同域下的脚本执行抛错，捕获异常的时候，不能拿到详细的异常信息，只能拿到类似 Script error 0. 这类信息。通常跨域的异常信息会被忽略，不会上报。解决方案： 所有 `<script>` 加载的资源加上 `crossorigin="anonymous"`

## 子应用热更新问题

garfish 子应用热更新问题请参考 [博客](/blog/hmr.md)

## cdn 第三方包未正确挂载在 window 上

> 问题概述

* 一般常见的基础库都有提供 cdn 的加载方式，这些 cdn 的基础库都会构建成 umd 格式，构建成 umd 格式的包，可以正常的支持各类环境的使用，当在浏览器环境时通常会将基础库的导出内容在 window 上添加一个环境变量，在基础库加载完成后可通过环境 window 上对应的环境变量使用基础库的一些方法
* 但是在微前端的子应用内，会发现在对应的基础库 cdn 加载完成后并未有效的挂在在 window 环境变量上，由于 v5 版本之前获取子应用导出内容的规范，子应用的 js 代码会运行在 commonjs 环境中，由于基础库构建成为了 umd 包，umd 的构建行为判断在 commonjs 环境中会将环境变量放置 exports 中，所以并未放置 window 环境变量

> 解决方案

* 将对应的 cdn script 增加 no-entry 属性：`<script no-entry="true" src="xxx"></script>`，设置该属性后对应的 script 内容将不会运行在 commonjs 环境，对应的环境变量也会正常的插入到子应用的 window 上

## SyntaxError: Identifier 'exports' has already been declared

> 问题概述

这个问题其实和上面那个 cdn 的问题，原因是一样的，由于 garfish 会注入一个 exports 变量，而子应用某个脚本（比如 vite 自己的热更引入的`react-refresh-runtime.development.js`）的代码也写了类似`const exports = {}`的代码，导致出现重复声明而报错。

> 解决方案

解决办法还是和上面加`no-entry`一样，不会注入 commonjs 相关的环境变量，但是，考虑到某些脚本可能是构建工具默认注入的，无法修改 script 标签，所以可以在 html 入口处加入以下配置代码来达到同样的效果（以 vite 的`react-refresh`为例）：

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>vue sub app</title>
    <!-- 必须是合法的JSON字符串，匹配规则很简单，就是实际加载的url字符串indexOf你的规则 -->
    <script type="garfish-config">
      {
        "sandbox": {
          "noEntryScripts": ["@react-refresh"]
        }
      }
    </script>
    <!-- 省略其它多余的代码 -->
  </head>
  <body>
    <div id="app"></div>
    <!-- 省略其它多余的代码 -->
  </body>
</html>
```

## ESModule

Garfish 核心库默认支持 esModule，但是需要关掉 vm 沙箱或者为快照沙箱时，才能够使用。

```js
Garfish.run({
  ...
  apps: [
    {
      name: 'vue'，
      activeWhen: '/vue',
      entry: 'http://localhost:8080',
      sandbox: {
        open: false,
        // snapshot: true, 或者只开启快照沙箱
      },
    },
  ],
})
```

如果需要在 vm 沙箱下开启 esModule 的能力，可以使用 `@garfish/es-module` 插件。

> `@garfish/es-module` 会在运行时分析子应用的源码做一层 esModule polyfill，但他会带来严重的首屏性能问题，如果你的项目不是很需要在 vm 沙箱下使用 esModule 就不应该使用此插件。

> 在短期的规划中，为了能在生产环境中使用，我们会尝试使用 wasm 来优化整个编译性能。在未来如果 [module-fragments](https://github.com/tc39/proposal-module-fragments) 提案成功进入标准并成熟后，我们也会尝试使用此方案，但这需要时间。

```js
import { GarfishEsModule } from '@garfish/es-module';

Garfish.run({
  ...
  plugins: [GarfishEsModule()],
})
```

> 提示：当子项目使用 `vite` 开发时，你可以在开发模式下使用 esModule 模式，生产环境可以打包为原始的无 esModule 的模式。

## 子应用堆栈信息丢失、sourcemap 行列信息错误

> 问题背景

微前端场景下，存在沙盒机制，基于 eval 和 new Function 的形式去实现沙箱机制，在手动执行代码的情况下，会产生堆栈丢失、sourcemap 还原错行等问题。

> 解决方案

可通过增加如下 webpack 配置解决：

```js
// webpack.config.js
const webpack = require('webpack');

config.plugins = [
  new webpack.BannerPlugin({
      banner: 'Micro front-end',
  });
]
```

具体原因可参考 [博客](/blog/sourcemap.md)



---
url: /hello.md
---

# Hello World!

## Start

Write something to build your own docs! 🎁



---
url: /index.md
---




---
url: /plugins/__meta__.md
---




---
url: /plugins/es-module.md
---


## garfish es-module plugin



---
url: /plugins/plugins.md
---


## Garfish 插件