@modern-js/main-doc 0.0.0-next-20221229063546 → 0.0.0-next-20221229142742

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.0-beta.7 build /github/workspace/packages/toolkit/main-doc
+> @modern-js/main-doc@2.0.0-beta.7 build /tmp/repo/modern.js/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/CHANGELOG.md

@@ -1,8 +1,8 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-20221229063546
+## 0.0.0-next-20221229142742
 
 ### Patch Changes
 
-- Updated dependencies [dda38c9c3e]
-  - @modern-js/builder-doc@0.0.0-next-20221229063546
+- Updated dependencies [dda38c9c3]
+  - @modern-js/builder-doc@0.0.0-next-20221229142742

package/en/docusaurus-plugin-content-docs/current/configure/app/deploy/microFrontend.md

@@ -0,0 +1,54 @@
+---
+sidebar_label: microFrontend
+---
+
+# deploy.microFrontend
+
+* 类型：`object`
+* 默认值：`{enableHtmlEntry: true, externalBasicLibrary: false}`
+
+```ts
+interface MicroFrontend {
+  enableHtmlEntry?: boolean;
+  externalBasicLibrary?: boolean;
+  moduleApp?: string;
+}
+```
+
+Developers can use the `deploy.microFrontend` to configure micro-frontend sub-application information.
+
+:::caution
+Enable the "Micro Frontend" features through `pnpm run new` first.
+:::
+
+## Example
+
+```ts
+export default defineConfig({
+  deploy: {
+    microFrontend: {
+      enableHtmlEntry: true
+    }
+  }
+});
+```
+
+## Configuration
+
+### enableHtmlEntry
+
+* Type: `boolean`
+
+* Default: `true`
+
+* Whether to enable the html entry, the default is `true`, the sub-application is built into the `HTML` mode, Garfish supports the `html` entry, you can turn on the open option, experience the corresponding features, and directly point the sub-application entry to the HTML entry when it is the HTML entry. Just point to the html of the sub-application
+* set it to `false` to indicate that the sub-application is built as `js`. After the sub-application is built as `js`, it cannot run independently. When it is a `JS` entry, point the entry file of the sub-application to the `JS` of the sub-application.
+
+
+### externalBasicLibrary
+
+* Type: `boolean`
+
+* Default: `false`
+
+Whether the `external` base library, when set to `true`, the current child application will be `external`: `react`, `react-dom`, Modern.js main application will automatically `setExternal` these two base libraries, if other types of frameworks Please add `react`, `react-dom` dependencies through `Garfish.setExternal`.

package/en/docusaurus-plugin-content-docs/current/configure/app/output/ssg.md

@@ -0,0 +1,226 @@
+---
+sidebar_label: ssg
+---
+# output.ssg
+
+* 类型： `boolean` | `object` | `function`
+* 默认值： `undefined`
+
+Enable the SSG for **Self-controlled Routing** or **Conventional Routing**.
+
+:::info
+For more routes detail, see [routes](/docs/guides/basic-features/routes)。
+:::
+
+## Example
+
+### Single Entry
+
+When the configuration is set to `true`, the SSG of all entries will be enabled by default.
+
+For **self-controlled routing**, the root route of the entry will be rendered. For **convention routing**, every route in the entry will be rendered.
+
+For example, the `src/` directory has the following file structure that satisfies **conventional routing**:
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+Make the following config in `modern.config.[tj]s`:
+
+```ts
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+After executing `pnpm build` to build the application. The `dist/` directory will generate three HTML for each of the three routes (only one HTML if SSG not enabled), and all HTML has been rendered.
+
+For example the following **self-controlled routing**:
+
+```tsx title="App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+Also using the above configuration, after executing `pnpm run build`, only the entry route `/` will generate the rendered HTML.
+
+### Multi Entries
+
+`output.ssg` can also be configured according to the entries, and the rules that the configuration takes effect are also determined by the entries routing method.
+
+例如以下目录结构：
+
+```bash
+。
+├── src
+│   ├── entryA
+│   │   └── routes
+│   │       ├── layout.tsx
+│   │       ├── page.tsx
+│   │       └── user
+│   │           ├── layout.tsx
+│   │           ├── page.tsx
+│   │           └── profile
+│   │               └── page.tsx
+│   └── entryB
+│       └── App.tsx
+```
+
+By default, all entryA entrances are rendered at build time after setting `output.ssg` to `true`. You can configure `false` to cancel the default behavior of the specified entries. For example, to cancel the rendering of the `entryA` at build time:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      entryA: true,
+      entryB: false,
+    },
+  },
+});
+```
+
+### Configure Route
+
+As mentioned above, **Self-Controlled Routing** only enables SSG configuration for entries route by default.
+
+Set specific routes in `output.ssg` can tell Modern.js to enable the SSG of these client side routes. For example, the content of the above `src/App.tsx` file is:
+
+```tsx title="src/App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+When set like this in `modern.config.[jt]s`, the `/about` route will also enable SSG:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+Modern.js will automatically concat the complete URL according to the entry and hand it over to the SSG plugin to complete the rendering.
+
+Request headers can also be configured for specific entries or routes, for example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {},
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {},
+        },
+      ],
+    },
+  },
+});
+```
+
+:::info
+The `headers` set in the route override the `headers` set in the entry.
+:::
+
+### Prevent Default
+
+By default, **Conventional Routing** all turn on SSG. Modern.js provides another field to prevent the default SSG behavior.
+
+For example, the following directory structure ，`/`、`/user` and `/user/profle` all have SSG enabled:
+
+```bash
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+You can set this to disable the default behavior of a client-side route:
+
+```js
+export default defineConfig({
+  output: {
+    preventDefault: ['/user'],
+  },
+});
+```
+
+### Dynamic Params
+
+Some routes may be dynamic, such as the `/user/:id` in a self-controlled route or the route generated by the `user/[id]/page.tsx` file in a conventional route.
+
+configure specific parameters in `output.ssg` to render the route of the specified parameters, for example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        {
+          url: '/user/:id',
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+The features of dynamic routing and SSG is useful when generating static pages in real time based on CMS system.

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/ssg.md

@@ -27,7 +27,7 @@ export default defineConfig({
 });
 ```
 
-SSG in **Conventional Routing** and **Self-control Routing** has different usage.
+SSG in **Conventional Routing** and **Self-controlled Routing** has different usage.
 
 ### Conventional Routing
 
@@ -84,7 +84,7 @@ Using **Conventional Routing**, each route will generate a HTML file. Looking at
 
 After executing `pnpm run serve` to start the project, visit the page in the Network, view the document returned by the request. The document contains the complete page content rendered by the component.
 
-### Self-control Routing
+### Self-controlled Routing
 
 **Self-controlled routing** is a custom routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, the user needs to inform the Modern.js framework in advance which routes need to enable the SSG.
 

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/data-fetch.md

@@ -427,7 +427,7 @@ export default () => {
     // No real request is sent here, just a hard coding data is returned.
     // In a real project, the data obtained from the remote end should be returned.
     return {
-      name: 'modern.js',
+      name: 'Modern.js',
     };
   });
 

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/framework-plugin/extend.md

@@ -0,0 +1,162 @@
+---
+title: 扩展插件 Hook
+sidebar_position: 5
+---
+
+本小节介绍如何通过动态注册 [Hook 模型](/docs/guides/topic-detail/framework-plugin/hook) 的方式来扩展插件 Hook。
+
+## 示例
+
+这里我们用一个简单的例子演示一下。假设我们要添加一些管理控制台输出信息的 Hook。
+
+首先我们初始化一个空的项目文件，并添加基础依赖：
+
+```console
+$ npx @modern-js/create modern-js-demo
+```
+
+### 创建 Hook
+
+我们先创建一个 Hook 模型：
+
+```ts title=config/plugin/MyPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+
+const message = createWaterfall<string[]>();
+```
+
+然后注册它：
+
+```ts title=config/plugin/MyPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+});
+```
+
+添加 Hook 类型：
+
+```ts title=config/plugin/MyPlugin.ts
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+### 使用 Hook
+
+创建插件，通过 `commands` Hook 函数，添加命令处理逻辑：
+
+```ts title=config/plugin/MyPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+```
+
+最后 `config/plugin/MyPlugin.ts` 的状态是：
+
+```ts title=config/plugin/MyPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+import type { CliPlugin } from '@modern-js/core';
+
+const message = createWaterfall<string[]>();
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  registerHook: {
+    message,
+  },
+
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+
+然后在 `modern.config.ts` 中添加这个插件：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from './config/plugin/MyPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就会执行相关逻辑，但由于没有收集到任何信息，所以控制台输出为空。
+
+那这里我们添加一个：
+
+```ts title=config/plugin/OtherPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+
+  setup(api) {
+    return {
+      message(list) {
+        return [...list, '[foo] line 0', '[foo] line 1'];
+      },
+    };
+  },
+});
+```
+
+将它添加到配置中：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import MyPlugin from './config/plugin/MyPlugin';
+import OtherPlugin from './config/plugin/OtherPlugin';
+
+export default defineConfig({
+  plugins: [MyPlugin(), OtherPlugin()],
+});
+```
+
+这时运行 `npx modern message` 就可以在控制台看到信息了：
+
+```console
+$ modern message
+[foo] line 0
+[foo] line 1
+```
+
+以上面这种方式就可以扩展出拥有各种能力的插件 Hook。