@modern-js/main-doc 2.8.0 → 2.10.0

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/model/computed-state.mdx

@@ -0,0 +1,153 @@
+---
+sidebar_position: 4
+title: Derived State
+---
+
+# Derived State
+
+In some scenarios, components need to perform further calculations on the State in Model before they can be used in the components. This logic can be directly written in the component or implemented through derived states in Model. Derived states are defined under the `computed` field in the Model. Depending on the dependencies of the Model and the return type, there are three ways to define derived states.
+
+## Only Depend on the Model's Own State
+
+The derived state only depends on the current Model's State, which is passed as the first parameter to the derived state's definition function.
+
+For example, the todo application has `items` and `filter` in its State, and `filter` is used to filter the todo items displayed on the current page. Therefore, we define a `visibleTodos` derived state that can be directly used in the component. The sample code is as follows:
+
+```ts
+/**
+ *  Assuming the structure of the todo item is as follows:
+{
+    id: string;          // id
+    text: string;        // todo
+    completed: boolean;
+}
+**/
+
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    filter: 'ALL', // ALL: show all；COMPLETED: show completed；ACTIVE: show active
+  },
+  computed: {
+    visibleTodos: state => {
+      switch (state.filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+```
+
+Derived state will eventually be merged with the Model's State, so the derived state can be accessed through the Model's State object. For example, the `visibleTodos` can be used in the component as follows:
+
+```ts
+function Todo() {
+  const [state, actions] = useModel(todoModel);
+
+  return (
+    <div>
+      <div>
+        {state.visibleTodos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Dependent State from Other Models
+
+In addition to depending on the current model's state, derived states may also depend on the state of other models. In this case, the definition format for the derived state is:
+
+
+```ts
+[stateKey]: [...depModels, (selfState, ...depModels) => computedState]
+```
+
+The following example demonstrates how the derived state `combinedValue` of `barModel` depends on the state of `fooModel`.
+
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    value: 'foo',
+  },
+  computed: {
+    combinedValue: [
+      fooModel,
+      (state, fooState) => state.value + fooState.value,
+    ],
+  },
+});
+```
+
+## Derived State with Function Type
+
+Derived states can also return a function. In this case, the definition format for the derived state is:
+
+```ts
+[stateKey]: (state) => (...args) => computedState    // Only relies on its own state
+[stateKey]: [...depModels, (selfState, ...depModels) => (...args) => computedState]  // Relies on the state of other models
+```
+
+Assuming the `filter` state is not stored in the state of the todo app, but is instead used directly in the component, `visibleTodos` can be a function type value. This function receives the `filter` parameter when used in the component, as shown below:
+
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+  },
+  computed: {
+    visibleTodos: state => filter => {
+      switch (filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+
+function Todo(props) {
+  // use props pass filter
+  const { filter } = props;
+  const [state, actions] = useModel(todoModel);
+
+  // get final todos
+  const todos = state.visibleTodos(filter);
+
+  return (
+    <div>
+      <div>
+        {todos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+:::info Additional Reference
+[Using Models](/guides/topic-detail/model/computed-state)
+:::

package/docs/en/guides/troubleshooting/cli.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# CLI FAQ
+
+### Can't pass command line arguments correctly when using pnpm?
+
+The pnpm v6 and pnpm v7 versions do not use the same posture when executing commands. The following should be noted:
+
+pnpm v7:
+
+When using pnpm to invoke a command in `package.json`, if you need to pass arguments to pnpm, you need to put the arguments before the command.
+
+For example, execute the prepare command with the pnpm '--filter' parameter:
+
+```bash
+pnpm run --filter "./packages/**" prepare
+```
+
+If you need to pass parameters to a command, you need to put the parameters after the command.
+
+For example, in the following `package.json` configuration:
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+The way to carry parameters when executing the command command is:
+
+```bash
+pnpm run command --options
+```
+
+pnpm v6:
+
+In the following `package.json` configuration:
+
+```json
+{
+  "scripts": {
+    "command": "modern command"
+  }
+}
+```
+
+If you need to execute `modern command --option`,
+
+When using pnpm, you need to execute the `pnpm run command -- --option`.
+
+This is because pnpm does not handle command parameters the same as Yarn, but is similar to npm: when not adding a `--` character string, the parameters of pnpm are passed; when using a `--` character string, the parameters of the execution script are passed.
+
+In the above example the parameter `--option` is passed to `modern command`. If `pnpm run command --option` is executed, the parameter `--option` will be passed to pnpm.
+
+Summary:
+
+**When using pnpm v7, if you pass arguments to pnpm, you need to put the arguments before the command**
+
+**When using pnpm v6, if the parameter passed to pnpm, you do not need to add `--`; if the parameter passed is for script use, you need to add `--` character string**.