@modern-js/main-doc 2.0.0-beta.3 → 2.0.0-beta.4

package/en/docusaurus-plugin-content-docs/current.json

@@ -4,7 +4,7 @@
     "description": "The label for version current"
   },
   "sidebar.tutorialsSidebar.category.基础": {
-    "message": "基础",
+    "message": "Basic",
     "description": "The label for category 基础 in sidebar tutorialsSidebar"
   },
   "sidebar.tutorialsSidebar.category.创建第一个应用": {
@@ -56,23 +56,23 @@
     "description": "The label for category 11: 添加容器组件 in sidebar tutorialsSidebar"
   },
   "sidebar.guidesSidebar.category.开始": {
-    "message": "开始",
+    "message": "Start",
     "description": "The label for category 开始 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.核心概念": {
-    "message": "核心概念",
+    "message": "Core Concept",
     "description": "The label for category 核心概念 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.基础功能": {
-    "message": "基础功能",
+    "message": "Basic Features",
     "description": "The label for category 基础功能 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.CSS 开发方案": {
-    "message": "CSS 开发方案",
+    "message": "CSS Development",
     "description": "The label for category CSS 开发方案 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.进阶功能": {
-    "message": "进阶功能",
+    "message": "Advanced Features",
     "description": "The label for category 进阶功能 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.BFF": {
@@ -80,15 +80,15 @@
     "description": "The label for category BFF in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.专题详解": {
-    "message": "专题详解",
+    "message": "Topic Detail",
     "description": "The label for category 专题详解 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.Reduck 状态管理": {
-    "message": "Reduck 状态管理",
+    "message": "Reduck State Manager",
     "description": "The label for category Reduck 状态管理 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.微前端": {
-    "message": "微前端",
+    "message": "Micro-frontend",
     "description": "The label for category 微前端 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.Monorepo": {
@@ -96,11 +96,11 @@
     "description": "The label for category Monorepo in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.包版本管理": {
-    "message": "包版本管理",
+    "message": "Package Version Manager",
     "description": "The label for category 包版本管理 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.自定义插件": {
-    "message": "自定义插件",
+    "message": "Customized plugins",
     "description": "The label for category 自定义插件 in sidebar guidesSidebar"
   },
   "sidebar.guidesSidebar.category.项目生成器": {

package/package.json

@@ -11,20 +11,20 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.0.0-beta.3",
+  "version": "2.0.0-beta.4",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "2.0.0-beta.3"
+    "@modern-js/builder-doc": "2.0.0-beta.4"
   },
   "devDependencies": {
     "ts-node": "^10",
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.0.0-beta.3"
+    "@modern-js/builder-doc": "2.0.0-beta.4"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/commands/inspect.md

@@ -33,7 +33,3 @@ modern inspect --env production
 ### SSR 配置
 
 如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.ssr.inspect.js` 文件，对应 SSR 构建时的 webpack 配置。
-
-### Modern 配置
-
-如果项目开启了 [enableModernMode](/docs/configure/app/output/enable-modern-mode) 选项，则在 `dist` 目录会另外生成一份 `webpack.modern.inspect.js` 文件，对应现代浏览器的 webpack 配置。

package/zh/apis/app/commands/new.md

@@ -34,7 +34,7 @@ $ npx modern new
 ? 请填写入口名称 entry
 ```
 
-### 启用启用可选功能
+### 启用可选功能
 
 在应用工程中，执行 `new` 命令启用可选能力如下：
 

package/zh/apis/app/hooks/src/index_.md

@@ -12,11 +12,12 @@ sidebar_position: 3
 只需要 `src/index.[tj]s` 默认导出函数:
 
 ```js title=src/index.js
-import { bootstrap } from '@modern-js/runtime';
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@edenx/runtime';
 
-export default App => {
+export default (App: React.ComponentType) => {
   // do something before bootstrap...
-  bootstrap(App, 'root');
+  bootstrap(App, 'root', undefined, ReactDOM);
 };
 ```
 
@@ -28,8 +29,8 @@ export default App => {
 
 ```js title=src/index.jsx
 import React from 'react';
-import ReactDOM from 'react-dom';
+import ReactDOM from 'react-dom/client';
 import App from './App';
 
-ReactDOM.render(<App />, document.getElementById('root'));
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
 ```

package/zh/components/debug-app.md

@@ -0,0 +1,18 @@
+在项目中执行 `pnpm run dev` 即可启动项目：
+
+```bash
+$ pnpm run dev
+
+> modern dev
+
+info    Starting dev server...
+info    App running at:
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.58.87:8080/
+  > Network:  http://10.254.68.105:8080/
+
+ Client ✔ done in 76.10ms
+```
+
+在浏览器中打开 `http://localhost:8000/`，可以看到页面内容。

package/zh/components/global-proxy.md

@@ -0,0 +1,28 @@
+
+Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`，该插件底层基于 [whistle](https://github.com/avwo/whistle)，可用来查看、修改 HTTP/HTTPS 的请求和响应，也可作为 HTTP 代理服务器使用。
+
+### 设置代理规则
+
+引入代理插件并填写规则后，执行 `pnpm run dev`，Modern.js 会在开发服务器启动之后，自动启用代理服务器。
+
+具体代理规则，可通过 [`dev.proxy`](/docs/configure/app/dev/proxy) 选项或 `config/proxy.js` 文件进行设置。
+
+### 代理服务器 UI 界面
+
+安装代理插件并配置代理规则后， 执行 `pnpm run dev` 命令：
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+在控制台中可以看到代理服务器成功启动。
+
+访问 `http://localhost:8899`，显示下图所示的 UI 界面后，即可通过界面设置规则。
+
+![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/zh/components/init-app.md

@@ -0,0 +1,44 @@
+
+Modern.js 生成器会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+
+```bash
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```
+
+在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
+
+```bash
+[INFO] 依赖自动安装成功
+[INFO] git 仓库初始化成功
+[INFO] 创建成功！
+可在新项目的目录下运行以下命令：
+pnpm run dev          # 按开发环境的要求，运行和调试项目
+pnpm run build        # 按产品环境的要求，构建项目
+pnpm run start        # 按产品环境的要求，运行项目
+pnpm run lint         # 检查和修复所有代码
+pnpm run new          # 继续创建更多项目要素，比如应用入口
+```
+
+:::note
+Modern.js 生成器除了在项目初始化时工作外，也能在后续研发中生成项目各种粒度的模块，并非一用即抛开。
+:::
+
+现在，项目结构如下：
+
+```
+.
+├── node_modules
+├── src
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+├── modern.config.ts
+├── package.json
+├── pnpm-lock.yaml
+├── README.md
+└── tsconfig.json
+```

package/zh/components/prerequisites.md

@@ -0,0 +1,19 @@
+### Node.js
+
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 16.18.1
+
+Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
+
+然后只要仓库根目录下有内容为 `lts/fermium` 或 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+:::

package/zh/configure/app/server/routes.md

@@ -52,16 +52,14 @@ export default defineConfig({
       "entryName": "page-a",
       "entryPath": "html/page-a/index.html",
       "isSPA": true,
-      "isSSR": false,
-      "enableModernMode": false
+      "isSSR": false
     },
     {
       "urlPath": "/b",
       "entryName": "page-a",
       "entryPath": "html/page-a/index.html",
       "isSPA": true,
-      "isSSR": false,
-      "enableModernMode": false
+      "isSSR": false
     },
   ]
 }

package/zh/configure/app/tools/esbuild.md

@@ -3,59 +3,36 @@ title: tools.esbuild
 sidebar_label: esbuild
 ---
 
-* 类型： `Object`
-* 默认值： `undefined`
+- 类型： `Object`
+- 默认值： `undefined`
 
 ## 介绍
 
-esbuild 是使用 Go 语言编写的 JavaScript Bundler/Minifier，它的特点是速度极快。在代码压缩方面，相比 webpack 内置的 terser 压缩器，esbuild 在性能上有数十倍的提升。
-
-Modern.js 基于 esbuild 提供了代码编译和压缩的能力，在大型工程中开启后，**可以大幅度减少代码压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
-
-使用 esbuild 压缩虽然带来了构建效率上的提升，但 esbuild 的压缩比例是低于 terser 的，因此**构建产物的体积会增大**，请根据业务情况酌情使用（比较适合中后台场景）。
-
-对于压缩工具之间的详细对比，可以参考 [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks)。
-
-:::info
-除了代码压缩外，esbuild 也可以代替 babel 进行代码编译，优点是可以提升编译速度，缺点是无法使用丰富的 babel 插件能力。
+:::tip esbuild 介绍
+[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，相比 webpack 内置的 terser 压缩器，esbuild 在性能上有数十倍的提升。
 :::
 
-## 配置项
-
-### target
+Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。在大型工程中开启后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
 
-* 类型： `string | string[]`
-* 默认值： `'esnext'`
-
-为生成的 JavaScript 和 CSS 代码设置目标环境。
-
-可以直接设置为 JavaScript 语言版本，比如 `es5`，`es6`，`es2020`。也可以设置为若干个目标环境，每个目标环境都是一个环境名称后跟一个版本号。比如 `['chrome58', 'edge16' ,'firefox57']`。
-
-支持设置以下环境：
+## 配置项
 
-- chrome
-- edge
-- firefox
-- ie
-- ios
-- node
-- opera
-- safari
+你可以通过 `tools.esbuild` 配置项来设置 esbuild 编译行为。
 
-默认情况下，esbuild 压缩过程中会引入 ES6 代码，比如模板字符串。如果需要兼容 ES5，可以将 `target` 设置为 `es5`。
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
 
-```typescript title="modern.config.ts"
 export default defineConfig({
   tools: {
     esbuild: {
-      target: 'es5',
+      loader: {
+        target: 'chrome61',
+      },
+      minimize: {
+        target: 'chrome61',
+      },
     },
   },
 });
 ```
 
-:::info
-设置 `target` 为 `es5` 时，需要保证所有代码被 babel 转义为 es5 代码，否则会导致 esbuild 编译报错：`Transforming 'xxx' to the configured target environment ("es5") is not supported yet`。
-
-`target` 字段的详细介绍可以参考 [esbuild - target](https://esbuild.github.io/api/#target)。
-:::
+完整配置项请参考 [Modern.js Builder - esbuild 插件配置](https://modernjs.dev/builder/zh/plugins/plugin-esbuild.html#%E9%85%8D%E7%BD%AE)。

package/zh/guides/advanced-features/bff/bff-proxy.md

@@ -5,7 +5,7 @@ title: 使用 BFF 代理
 
 通过配置 BFF 代理，无需手动写码，即可对 API 请求进行转发。
 
-::: caution
+:::caution
 使用 BFF 代理需确保请求能进入 BFF handler。（例如请求路径必须包含 bff prefix）
 :::
 

package/zh/guides/advanced-features/compatibility.md

@@ -25,8 +25,8 @@ Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-C
 可以通过微生成器开启该功能：
 
 ```bash
-? 请选择你想要的操作：启用可选功能
-? 启用可选功能：启用「基于 UA 的 Polyfill」功能
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「基于 UA 的 Polyfill」功能
 ```
 
 安装依赖后，配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run start` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
@@ -40,42 +40,6 @@ Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-C
 
 ![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
 
-
-## 差异化分发
-
-Modern.js 提供了运行时基于浏览器 User Agent 的差异化分发方案, 设置 [`output.enableModernMode`](/docs/configure/app/output/enable-modern-mode) 后， 生产环境会自动构建出针对现代浏览器语法未降级的 JS 产物和针对旧版本浏览器带有 Polyfill 的 JS 产物:
-
-```bash title="dist/static/js"
-├── 370.95db0e84-es6.js
-├── 370.95db0e84-es6.js.map
-├── 370.ace5d8a0.js
-├── 370.ace5d8a0.js.map
-├── main.64eb3bc7-es6.js
-├── main.64eb3bc7-es6.js.map
-├── main.c8aab430.js
-├── main.c8aab430.js.map
-├── runtime-main.9ad9a46b-es6.js
-├── runtime-main.9ad9a46b-es6.js.map
-├── runtime-main.dccca6e0.js
-└── runtime-main.dccca6e0.js.map
-```
-
-同时 HTML 也会构建出对应的 ES6 版本:
-
-```js title="dist/html/main/index-es6.html"
-<script defer="defer" src="/static/js/370.95db0e84-es6.js"></script>
-```
-
-```js title="dist/html/main/index.html"
-<script defer="defer" src="/static/js/370.ace5d8a0.js"></script>
-```
-
-通过 `pnpm run build && pnpm run start` 启动服务器, 访问页面时，会根据浏览器信息决定返回 `index-es6.html` 还是 `index.html`。
-
-:::info 注
-内部目前使用 [@babel/compat-data](https://github.com/babel/babel/blob/main/packages/babel-compat-data/data/native-modules.json) 来判断具体浏览器是否支持 es6 语法。
-:::
-
 ## Browserslist 配置
 
 Modern.js 支持在项目根目录 `package.json` 文件中的 `browserslist` 字段（或单独的 `.browserslistrc` 文件）指定项目覆盖的目标浏览器范围。该值会被 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 和 [`autoprefixer`](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。

package/zh/guides/advanced-features/custom-app.md

@@ -16,7 +16,7 @@ import ReactDOM from 'react-dom/client'
 import { bootstrap } from '@modern-js/runtime';
 
 
-export default App => {
+export default (App: React.ComponentType) => {
   // do something before bootstrap...
   bootstrap(App, 'root', undefined, ReactDOM);
 };
@@ -29,32 +29,30 @@ export default App => {
 Modern.js 生成的文件内容如下：
 
 ```js
-import customRender from '@/src/index.js';
-import { createApp, bootstrap } from '@modern-js/runtime';
 import React from 'react';
-import App from '@/src/App';
+import ReactDOM from 'react-dom/client';
+import customBootstrap from '@_edenx_src/index.tsx';
+import App from '@_edenx_src/App';
+import { router, state } from '@edenx/runtime/plugins';
 
-const IS_BROWSER = typeof window !== 'undefined';
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
 const MOUNT_ID = 'root';
 
 let AppWrapper = null;
 
-const renderApp = () => {
+function render() {
   AppWrapper = createApp({
     // runtime 的插件参数...
-  })(App);
-  customRender(AppWrapper);
-};
-
-renderApp();
+  })(App)
+  if (IS_BROWSER) {
+    customBootstrap(AppWrapper);
+  }
+  return AppWrapper
+}
 
-export default AppWrapper;
+AppWrapper = render();
 
-if (IS_BROWSER && module.hot) {
-  module.hot.accept('<path>/src/App', () => {
-    renderApp();
-  });
-}
+export default AppWrapper;;
 ```
 
 ## 完全接管 Webpack 入口

package/zh/guides/advanced-features/ssg.md

@@ -12,8 +12,8 @@ SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `de
 我们首先需要执行 `pnpm run new` 启用 SSG 功能：
 
 ```bash
-? 请选择你想要的操作： 启用可选功能
-? 启用可选功能： 启用「SSG」功能
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「SSG」功能
 ```
 
 SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
@@ -49,7 +49,7 @@ SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 
 在 `src/routes/page.tsx` 中添加组件代码：
 
-```jsx title="src/pages/index.tsx"
+```jsx title="src/routes/page.tsx"
 export default () => {
   return  <div>Index Page</div>
 }
@@ -133,7 +133,7 @@ export default defineConfig({
 修改上述 `src/App.ts` 的代码为：
 
 ```tsx title="App.ts"
-import { useRuntimeContext, useStaticLoader } from '@modern-js/runtime';
+import { useRuntimeContext, useLoader } from '@modern-js/runtime';
 import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
 import { StaticRouter } from '@modern-js/runtime/router/server';
 
@@ -142,9 +142,9 @@ const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
 export default () => {
   const { context } = useRuntimeContext();
 
-  const { data } = useStaticLoader(async () => ({
+  const { data } = useLoader(async () => ({
     message: Math.random(),
-  }));
+  }), { static: true });
 
   return (
     <Router location={context.request.pathname}>