@modern-js/main-doc 2.7.0 → 2.9.0

package/docs/en/guides/topic-detail/micro-frontend/c01-introduction.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+title: Introduction
+---
+# Introduction
+
+Micro frontend is an architecture similar to microservices. It is an architectural style composed of multiple front-end applications delivered independently. It decomposes the front-end application into some smaller and simpler applications that can be independently developed, tested and deployed., while still a cohesive single product in the eyes of users.
+
+It mainly solves two problems:
+
+- As the iterative application of the project becomes larger and more difficult to maintain.
+- Collaborative development of projects across teams or departments leads to inefficiencies.
+
+## Keyword
+
+In the micro frontend, applications are divided into **main application**, and **sub-applications**.
+
+- Main application: The base project of the micro frontend project, all sub-applications will be loaded by it.
+- Sub-application: An application developed and deployed independently will eventually be loaded by the main application.
+
+## Features
+
+- Base on [Garfish](https://www.garfishjs.org/guide)
+- Generator supports
+- Support React component-based reference micro-front-end sub-application
+- Support loading
+- Support main application online and sub-application offline debugging mode
+
+You can learn how to develop a micro frontend master app in the section [Experience micro frontend](/guides/topic-detail/micro-frontend/c02-development).

package/docs/en/guides/topic-detail/micro-frontend/c02-development.mdx

@@ -0,0 +1,254 @@
+---
+sidebar_position: 2
+title: development
+---
+
+# Experience Micro Frontend
+
+Through this chapter you can learn:
+
+- How to create the main application and sub-application of the micro frontend project.
+- Basic process of micro frontend project development.
+
+## Create an app
+
+Currently supports two routing modes
+- Self-controlled routing
+- Conventional routing
+
+First, clarify the routing mode of the main application [create a conventional routing main application](#创建约定式路由主应用) or [create a self-controlled routing main application](#创建自控式路由主应用)
+
+In this experience we will create two sub-applications Table and Dashboard for the main application (Table is reduced routing, Dashboard is self-controlled routing)
+
+
+### File-based Routing Main App
+
+Initialize the project with a command line:
+
+```bash
+mkdir masterApp && cd masterApp
+npx @modern-js/create
+```
+
+After the project is created, we can enable the `micro frontend` through `pnpm run new`:
+
+```bash
+? Action Enable features
+? Enable features Enable Micro Front-end Feature
+```
+
+Next, let's register the micro frontend plugin and add the main micro frontend app and add the list of sub-apps:
+
+import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
+
+<EnableMicroFrontend />
+
+Then we create two new directories in the routes folder
+- table (for loading conventional routing sub-applications)
+- dashboard (for loading self-controlled routing sub-applications)
+
+In these two directories, we need to create a `$.tsx` file as the entry of the main application convention route ($represents fuzzy match, that is, `/table` and `/table/test` will match this `$.tsx` as the entry file of the route, which will ensure that the sub-application route is loaded correctly in the micro frontend scenario)
+
+#### Load file-base routing sub-app
+
+```js title="src/routes/table/$.tsx"
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+const Index = () => {
+  const { Table } = useModuleApps();
+
+  return (
+    <div>
+      <Table />
+    </div>
+  )
+}
+
+export default Index;
+```
+
+#### Load self-controlled routing sub-app
+
+```js title="src/routes/dashboard/$.tsx"
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+const Index = () => {
+  const { Dashboard } = useModuleApps();
+
+  return (
+    <div>
+      <Dashboard />
+    </div>
+  )
+}
+
+export default Index;
+```
+#### route link
+
+At this time, the main application configuration has been completed, and the sub-application can be loaded through the route, and the `layout.tsx` of the main application can be modified to jump to the route:
+
+```js title="src/route/layout.tsx"
+import { Outlet, Link } from '@modern-js/runtime/router';
+
+const Layout = () => (
+  <div>
+    <div><Link to={'/table'}>Load file-base routing sub-app</Link></div>
+    <div><Link to={'/dashboard'}>Load self-controlled routing sub-app</Link></div>
+    <div><Link to={'/'}>unmount sub-app</Link></div>
+    <Outlet />
+  </div>
+);
+
+export default Layout;
+```
+
+### Self-Controlled Main App
+
+Initialize the project with a command line:
+
+```bash
+mkdir masterApp && cd masterApp
+npx @modern-js/create
+```
+
+After the project is created, we can enable the `micro frontend` function through `pnpm run new`:
+
+```bash
+? Action Enable features
+? Enable features Enable Micro Front-end Feature
+```
+
+Next, let's register the micro frontend plugin and add the main micro frontend app and add the list of sub-apps:
+
+<EnableMicroFrontend />
+
+Since it is a self-controlled route, we delete the `routes/` folder and add the `App.tsx` file in the `src/` directory. If you use a `non-MApp` component here, you need to use the `createBrowserRouter` API of '=React Router v6 to create routes.
+
+#### Load sub-app
+
+import CustomRouterMicroFrontend from "@site-docs/components/custom-router-micro-frontend";
+
+<CustomRouterMicroFrontend />
+
+### File-based sub-app
+
+Initialize the project with a command line:
+
+```bash
+mkdir table && cd table
+npx @modern-js/create
+```
+
+After create sub-app. We execute `pnpm run new` to enable the `micro frontend` function:
+
+```bash
+? Action Enable features
+? Enable features Enable Micro Front-end Feature
+```
+
+Next, let's register the micro frontend plugin and modify `modern.config.ts` to add the configuration of the micro frontend sub-app `deploy.microFrontend`:
+
+```js title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import garfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  dev: {
+    port: 8081
+  },
+  runtime: {
+    router: true,
+    state: true,
+  },
+  deploy: {
+    microFrontend: true,
+  },
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+add `src/routes/page.tsx`:
+
+```js title="src/routes/page.tsx"
+const Index = () => {
+  return (
+    <div className="container-box">subApp</div>
+  )
+}
+
+export default Index;
+```
+
+### Self-controlled sub-app
+
+Initialize the project with a command line:
+
+```bash
+mkdir table && cd table
+npx @modern-js/create
+```
+
+After create sub-app. We execute `pnpm run new` to enable the `micro frontend` function:
+
+```bash
+? Action Enable features
+? Enable features Enable Micro Front-end Feature
+```
+
+Next, let's register the micro frontend plugin and modify `modern.config.ts` to add the configuration of the micro frontend sub-app `deploy.microFrontend`:
+
+```js title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import garfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  dev: {
+    port: 8082
+  },
+  runtime: {
+    router: true,
+    state: true,
+  },
+  deploy: {
+    microFrontend: true,
+  },
+  plugins: [appTools(), garfishPlugin()],
+});
+```
+
+Self-controlled routing needs to delete the `routes/` folder and create a new `App.tsx` in the `src/` directory.
+
+And add code in `src/App.tsx`, note that you need to parse from `props` and pass `basename` to `BrowserRouter`.
+
+```js title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+
+export default (props: {basename: string}) => {
+  const { basename } = props;
+
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route index element={<div>Self-controlled route root</div>} />
+        <Route path={'path'} element={<div>Self-controlled sub route</div>} />
+      </Routes>
+    </BrowserRouter>
+  );
+};
+```
+
+## Debug
+
+Start the application by executing the `pnpm run dev` command in the directory in sequence:
+- masterApp `http://localhost:8080`
+- table subapplication (conventional routing) `http://localhost:8081`
+- dashboard subapplication (self-controlled routing) `http://localhost:8082`
+
+Access the main application address `http://localhost:8080`
+
+After completing the experience of the overall development process of micro frontend, you can learn more about how to [develop the main application](/guides/topic-detail/micro-frontend/c03-main-app).
+
+## FAQ
+
+Garfish issue: https://www.garfishjs.org/issues/

package/docs/en/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -0,0 +1,282 @@
+---
+sidebar_position: 3
+title: Develop Main App
+---
+# Develop Main App
+
+In the previous [Experience micro frontend](/guides/topic-detail/micro-frontend/c02-development), an example was used to demonstrate how to create and configure micro frontend sub-applications. Through this chapter, you can further understand how to develop the main application, and its common configuration.
+
+After creating an application project through the `@modern-js/create` command, you can execute `pnpm run new` in the project (the `modern new` command is actually executed). After selecting the 「micro frontend」 mode, the micro frontend will be installed. Dependencies, just register the plugin manually.
+
+import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
+
+<EnableMicroFrontend />
+
+## Register Sub-app
+
+When the information is provided on the `masterApp` configuration, the application will be considered the main application. At present, there are two configuration methods for sub-app information, and these two methods are applied to different scenarios.
+
+### Register sub-app info directly
+
+You can register the sub-application information directly through the configuration:
+
+:::tip
+It can be configured at runtime via the API [defineConfig](/apis/app/runtime/app/define-config).
+
+When the parameter is a function, it cannot be serialized to the product code, so please configure it through defineConfig when it comes to configuration such as functions
+:::
+
+import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
+
+<MicroRuntimeConfig />
+
+### Custom remote app list
+
+This function allows you to pull a list of remote child applications and register them with the runtime framework:
+
+```ts title="App.tsx"
+defineConfig(App, {
+  masterApp: {
+    manifest: {
+      getAppList: async () => {
+        // get from remote api
+        return [{
+          name: 'Table',
+          entry: 'http://localhost:8001',
+          // activeWhen: '/table'
+        }, {
+          name: 'Dashboard',
+          entry: 'http://localhost:8002'
+          // activeWhen: '/dashboard'
+        }];
+      },
+    },
+  },
+});
+```
+
+## Renderer sub-app
+
+There are two ways to load sub-app in micro frontend:
+
+1. **Sub-app component ** Get the components of each sub-app, and then you can render the sub-app of micro frontend just like using ordinary'React 'components.
+2. **Centralized routing** Through centralized routing configuration, the corresponding sub-app of rendering is automatically activated according to the current page `pathname`.
+
+### Sub-app component
+
+Developers can use the `useModuleApps` method to obtain the components of each child application.
+
+Through the combined use of the `router` component, developers can autonomously render different sub-applications according to different routes.
+
+Suppose our subapp list is configured as follows:
+
+<EnableMicroFrontend />
+
+`App.tsx` as follow:
+
+```js title="App.tsx"
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+
+import { RouterProvider, Route, createBrowserRouter, createRoutesFromElements, BrowserRouter, Link, Outlet } from '@modern-js/runtime/router';
+
+const AppLayout = () => (
+  <>
+    <div><Link to={'/table'}>load file-based sub-app</Link></div>
+    <div><Link to={'/dashboard'}>load self-controlled sub-app</Link></div>
+    <div><Link to={'/'}>unmount sub-app</Link></div>
+    <Outlet />
+  </>
+)
+
+export default () => {
+  const { apps, MApp } = useModuleApps();
+
+  // Instead of using the MApp component, you need to use createBrowserRouter to create the route
+  const router = createBrowserRouter(
+    createRoutesFromElements(
+      <Route path="/" element={<AppLayout />}>
+        {apps.map(app => {
+          const { Component } = app;
+          // Fuzzy match, path needs to be written in a pattern similar to abc/*
+          return (
+            <Route
+              key={app.name}
+              path={`${app.name.toLowerCase()}/*`}
+              element={
+              <Component
+                loadable={{
+                  loading: ({ pastDelay, error }: any) => {
+                    if (error) {
+                      return <div>error: {error?.message}</div>;
+                    } else if (pastDelay) {
+                      return <div>loading</div>;
+                    } else {
+                      return null;
+                    }
+                  },
+                }}
+              />
+              }
+            />
+          )
+        })}
+      </Route>
+    )
+  );
+
+  return (
+    // Use MApp to automatically load sub-applications according to the configured activeWhen parameters (this project is configured in modern.config.ts)
+    // <BrowserRouter>
+    //   <MApp />
+    // </BrowserRouter>
+
+    // Manually write the Route component to load the sub-application, which is convenient for scenarios that require pre-operation such as authentication
+    <>
+      <RouterProvider router={router} />
+    </>
+  );
+};
+```
+
+Here, the activation route of **Table** is customized as **/table** through the `Route` component, and the activation route of **Dashboard** is **/dashboard**.
+
+### Centralized routing
+
+**Centralized Routing** is a way to centrally configure active routes for subapps. We enable **Centralized Routing** by adding an `activeWhen` field to the subapp list information.
+
+<MicroRuntimeConfig />
+
+Use `useModuleApp` api in Main App, get `MApp` component and then render it
+
+```tsx title=Main App: App.tsx
+import { useModuleApp } from '@modern-js/plugin-garfish/runtime';
+
+function App() {
+  const { MApp } = useModuleApps();
+
+  return (
+    <div>
+      <MApp />
+    </div>
+  );
+}
+```
+
+After starting the application in this way, accessing the '/table' route will render the'Table 'sub-application, and accessing the'/dashboard 'route will render the'Dashboard' sub-application.
+
+
+### Mix Mode
+
+
+Of course, **sub-application components** and **centralized routing** can be mixed.
+
+
+- One molecular application is activated as a **sub-application component**, and the other part is activated as a **centralized routing**.
+- A molecular application can be activated either as a **centralized routing** or as a **sub-application component**.
+
+### Loading
+
+By configuring the `loadable` configuration, loading components can be added for 「centralized routing」 and 「sub-applicati」, and errors, timeouts, flashes, etc. can be considered, so as to provide users with a better user experience. The design and implementation of this function refer to [react-loadable](https://github.com/jamiebuilds/react-loadable), and the basic functions are similar.
+
+
+```tsx
+function Loading() {
+  return <div>Loading...</div>;
+}
+
+function App(){
+  return <>
+    <Table
+      loadable={{
+        loading: Loading,
+      }}
+    />
+  <>
+}
+```
+
+#### Add Error Status
+
+When the micro-frontend sub-application fails to load or render, the `loading component` will receive the `error` parameter (if there is no error, the error is null).
+
+```tsx
+function Loading({ error }) {
+  if (error) {
+    return <div>Error msg {error?.message}</div>;
+  } else {
+    return <div>Loading...</div>;
+  }
+}
+```
+
+#### Avoid Loading Flash Back
+
+Sometimes the display time of the loading component may be less than 200ms, and the loading component will flash back at this time. Many user studies have proved that the loading flash back situation will cause the user to perceive that the loading content takes longer than the actual time.
+
+When loading is less than 200ms, if the content is not displayed, the user will think it is faster.
+
+Therefore, the loading component also provides the `pastDelay` parameter, which will only be true when it exceeds the set delay display. You can set the delay duration through the `delay` parameter.
+
+```tsx
+function Loading({ error, pastDelay }) {
+  if (error) {
+    return <div>Error! {error?.message}</div>;
+  } else if (pastDelay) {
+    return <div>Loading...</div>;
+  } else {
+    return null;
+  }
+}
+```
+
+The default value of `delay` is `200ms`, you can set the delay display time through `delay` in `loadable`.
+
+```tsx
+
+function App(){
+  return <>
+    <Table
+      loadable={{
+        loading: Loading,
+        delay: 300 // 0.3 seconds
+      }}
+    />
+  <>
+}
+```
+
+#### Add Timeout State
+
+Sometimes because of the network, the micro-front-end sub-application fails to load, resulting in the loading state being displayed all the time, which is very bad for users, because they don't know the right response to get a specific response, whether they need to refresh the page, by Increasing the timeout state can solve this problem well.
+
+The loading component will get the `timeOut` parameter when timeout, when the micro frontend application loads timeout, it will get the `timeOut` property value of true.
+
+```tsx
+function Loading({ error, timeOut, pastDelay }) {
+  if (error) {
+    return <div>Error! {error?.message}</div>;
+  } else if (timeOut) {
+    return <div>Loading timed out, please refresh the page... </div>;
+  } else if (pastDelay) {
+    return <div>Loading...</div>;
+  } else {
+    return null;
+  }
+}
+```
+
+The timeout state is off and can be enabled by setting the `timeout` parameter in `loadable`:
+
+```tsx
+
+function App(){
+  return <>
+    <Table
+      loadable={{
+        loading: Loading,
+        timeOut: 10000 // 10s
+      }}
+    />
+  <>
+}
+```

package/docs/en/guides/topic-detail/micro-frontend/c04-communicate.mdx

@@ -0,0 +1,57 @@
+---
+sidebar_position: 4
+title: Communicate
+---
+# Communicate
+
+## Props
+
+In Modern.js, the sub-application will be wrapped into a React component, and the purpose of communicating between the main application and the sub-application can be achieved directly by passing'props' to the React component.
+
+```tsx title=Main: App.tsx
+function App() {
+  const { MApp } = useModuleApps();
+
+  return (
+    <div>
+      <MApp count={100} />
+    </div>
+  );
+}
+```
+
+```tsx title=Main: App.tsx
+function App(props) {
+  console.log(props);
+  return ...
+}
+```
+
+The child application will print `{count: 0}`. Currently, child application rendering responsiveness is not supported. Changing the data of'count 'on the main application in time will not trigger a view update
+
+## channel
+
+[Garfish.channel] (https://www.garfishjs.org/api/channel) Used for communication between applications. It is an instance of `EventEmitter2`.
+
+```ts
+// sub app listen login event
+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);
+    };
+  });
+};
+
+// main app emit login event
+api.getLoginInfo.then(res => {
+  if (res.code === 0) {
+    window.Garfish.channel.emit('login', res.data);
+  }
+});
+```

package/docs/en/guides/topic-detail/micro-frontend/c05-mixed-stack.mdx

@@ -0,0 +1,26 @@
+---
+sidebar_position: 5
+title: Mixed Stack
+---
+# Mixed Stack
+
+The Modern.js micro frontend scheme is based on the [Garfish](https://garfishjs.org/) package and provides some more out-of-the-box usage.
+
+When your main application and sub-application are not all Modern.js applications, you can refer to this document.
+
+1. The sub-app is **Modern.js**, the native Garfish micro frontend used by the main app.
+2. The main application is **Modern.js**, and some sub-applications have other technology stacks.
+
+## Modern.js Sub App
+
+**Modern.js** subapps compile to generate a standard [Garfish subapp export](https://www.garfishjs.org/guide/start#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0).
+So you can directly access the standard micro frontend main application.
+
+
+:::info
+The child application is **Modern.js**, when the main application uses the native Garfish micro frontend, the **child application debugging mode** is not available.
+:::
+
+## Modern.js Main App
+
+The Main App is **Modern.js**, and other technology stacks used by sub-applications. Sub-App can be developed according to [Garfish Sub-Application Standard](https://www.garfishjs.org/guide/demo/react).