docs: 进一步优化文档

2025-04-06 03:59:53 +08:00 · 2022-04-04 21:02:18 +08:00 · 2022-04-04 21:02:18 +08:00 · 7e1c3cc07b
commit 7e1c3cc07b
parent 4732acc233
12 changed files with 235 additions and 79 deletions
--- a/docs/.vuepress/configs/sidebar/en.ts
+++ b/docs/.vuepress/configs/sidebar/en.ts
@ -15,6 +15,7 @@ export const en: SidebarConfig = {
      text: '基础',
      children: [
        '/guide/directory-structure.md',
+        '/guide/builder.md',
        '/guide/config.md',
        '/guide/runtime-config.md',
        '/guide/env.md',
--- a/docs/.vuepress/configs/sidebar/zh.ts
+++ b/docs/.vuepress/configs/sidebar/zh.ts
@ -15,6 +15,7 @@ export const zh: SidebarConfig = {
      text: '基础',
      children: [
        '/zh/guide/directory-structure.md',
+        '/zh/guide/builder.md',
        '/zh/guide/config.md',
        '/zh/guide/runtime-config.md',
        '/zh/guide/env.md',
--- a/docs/zh/guide/builder.md
+++ b/docs/zh/guide/builder.md
@ -0,0 +1,22 @@
+# 支持 Vite 和 Webpack 双构建
+
+`Fes.js@2.1.x` 版本支持 Vite 和 Webpack 两种构建方式，不再内置构建方式，需要开发者自行选择:
+
+-   选用 Vite 构建，安装 `npm i @fesjs/build-vite` 依赖即可。
+-   选用 Webpack 构建，安装 `npm i @fesjs/build-webpack` 依赖即可。
+
+## 使用差异
+
+由于 Fes.js 在 Vite 和 Webpack 上做了一层封装，开发者关心的构建配置不会太多。从使用上来说，主要存在以下几个差异点：
+
+### 配置
+
+Webpack 和 Vite 构建在配置方面有一些差异，具体可以查阅[配置](../reference/config)。
+
+### 静态文件处理
+
+由于 Vite 的限制，不支持 `require` 语法，具体 Vite 的用法可以查看[官网](https://cn.vitejs.dev/guide/assets.html)
+
+### html 模版
+
+Webpack 对于 html 模版是没有什么限制的，而 Vite 推荐模版文件就放在项目根目录下。Webpack 有个非常强大的 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin)，Fes.js 引入了[vite-plugin-html](https://github.com/vbenjs/vite-plugin-html) 进行能力的对齐，如果开发者想要个性化定制模版，那么在配置上还是存在差异的。
--- a/docs/zh/guide/config.md
+++ b/docs/zh/guide/config.md
@ -1,45 +1,53 @@
-# 配置
+# 编译时配置

-Fes.js 约定 `.fes.js` 文件为项目编译需要配置文件，可以引入 node 端依赖项，不要引入浏览器端依赖项。
+Fes.js 约定 `.fes.js` 文件为项目编译需要编译时配置文件，可以引入 node 端依赖项，不要引入浏览器端依赖项。

-
-一份常见的配置示例如下：
+一份常见的配置示例如下（更多配置项请查阅[配置](../reference/config))：

 ```js
-export default {
+import { defineBuildConfig } from '@fesjs/fes';
+
+export default defineBuildConfig({
    base: '/foo/',
    publicPath: '/',
    devServer: {
-        port: 8080
+        port: 8080,
    },
    mock: {
-        prefix: '/v2'
+        prefix: '/v2',
    },
    proxy: {
        '/v2': {
-            'target': 'https://api.douban.com/',
-            'changeOrigin': true, 
+            target: 'https://api.douban.com/',
+            changeOrigin: true,
        },
    },
    layout: {
-        title: "Fes.js",
+        title: 'Fes.js',
        footer: 'Created by MumbelFe',
        multiTabs: false,
-        menus: [{
-            name: 'index'
-        }, {
-            name: 'onepiece'
-        }, {
-            name: 'store'
-        }, {
-            name: 'simpleList'
-        }]
-    }
-}
+        menus: [
+            {
+                name: 'index',
+            },
+            {
+                name: 'onepiece',
+            },
+            {
+                name: 'store',
+            },
+            {
+                name: 'simpleList',
+            },
+        ],
+    },
+});
 ```

 ## 本地临时配置文件
+
 可以新建 `.fes.local.js` 作为本地临时配置文件。这份配置会和 `.fes.js` 做 `deep merge` 后形成最终配置。
+
 ```js
 // .fes.js
 export default { mock: false };
@ -50,21 +58,26 @@ export default {
    devServer: { port: 8080 }
 };
 ```
+
 最终的配置是：
+
 ```js
 {
    mock: true,
    devServer: { port: 8080 }
 };
 ```
+
 ::: warning
-`.fes.local.js` 是本地验证使用的临时配置，仅在 `fes dev` 时有效，请将其添加到 `.gitignore`，务必不要提交到 `git` 仓库中。
+`.fes.local.js` 是本地验证使用的临时配置，仅在 `fes dev` 时有效，请将其添加到 `.gitignore`，不要提交到 `git` 仓库中。
 :::

 ## 多环境多份配置
+
 可以通过环境变量 `FES_ENV` 区分不同环境，来指定当前环境的配置文件，这份配置会和 `.fes.js` 做 `deep merge` 后形成最终配。

 比如配置如下：
+
 ```js
 // .fes.js
 export default { mock: false };
@ -75,11 +88,15 @@ export default {
    devServer: { port: 8080 }
 };
 ```
+
 当我们运行：
+
 ```bash
 FES_ENV=uat fes dev
 ```
+
 这时候会命中 `.fes.uat.js` 这份环境配置，最终配置是：
+
 ```js
 {
    mock: true,
--- a/docs/zh/guide/runtime-config.md
+++ b/docs/zh/guide/runtime-config.md
@ -8,20 +8,75 @@ Fes.js 框架跟传统开发模式不一样。传统开发模式中用户编写

 例如：

-plugin-acess插件定义运行时配置项：
+plugin-acess 插件定义运行时配置项：
+
 ```js
 api.addRuntimePluginKey(() => 'access');
 ```
-plugin-acess插件读取配置项：
+
+plugin-acess 插件读取配置项：
+
 ```js
 const runtimeConfig = plugin.applyPlugins({
    key: 'access',
    type: ApplyPluginsType.modify,
-    initialValue: {}
+    initialValue: {},
 });
 ```

 而用户则只需要配置：
+
+```js
+// app.js
+import { defineBuildConfig } from '@fesjs/fes';
+
+export default defineRuntimeConfig({
+    access: memo => ({
+        ...memo
+        unAccessHandler({
+            router, to, from, next
+        }) {
+            // 处理逻辑
+        },
+        noFoundHandler({
+            router, to, from, next
+        }) {
+            // 处理逻辑
+        },
+    }),
+});
+```
+
+## 配置智能提示
+
+配置可以单独导出，也可以通过 `defineRuntimeConfig` 工具函数获取类型提示。
+
+方式一（推荐，有类型提示）：
+
+```js
+// app.js
+import { defineBuildConfig } from '@fesjs/fes';
+
+export default defineRuntimeConfig({
+    access: memo => ({
+        ...memo
+        unAccessHandler({
+            router, to, from, next
+        }) {
+            // 处理逻辑
+        },
+        noFoundHandler({
+            router, to, from, next
+        }) {
+            // 处理逻辑
+        },
+    }),
+    // ...其他配置项
+});
+```
+
+方式二：
+
 ```js
 // app.js
 export const access = memo => ({
@ -37,7 +92,6 @@ export const access = memo => ({
        // 处理逻辑
    },
 });
-
 ```

 ## 配置项
@ -49,6 +103,7 @@ beforeRender(lastOpts)
 在渲染之前执行，执行`action`过程中显示 `loading` 配置的组件，执行结果作为参数 `initialState` 传给 `modifyClientRenderOpts`。

 示例：
+
 ```js
 // app.js
 import { access } from '@fesjs/fes';
@ -65,24 +120,24 @@ export function beforeRender(lastOpts) {
                setTimeout(() => {
                    setRole('admin');
                    resolve({
-                        userName: 'harrywan'
+                        userName: 'harrywan',
                    });
                }, 1000);
            });
-        }
-    }
-};
+        },
+    };
+}
 ```

 ### patchRoutes

 patchRoutes({routes })

-
 修改路由。

 比如在最前面添加一个 /foo 路由：
-```
+
+```js
 export function patchRoutes({ routes }) {
    routes.unshift({
        path: '/foo',
@ -90,6 +145,7 @@ export function patchRoutes({ routes }) {
    });
 }
 ```
+
 :::tip
 直接修改 `routes`, 不需要返回
 :::
@ -99,11 +155,13 @@ export function patchRoutes({ routes }) {
 modifyClientRenderOpts(lastOpts)

 修改 `clientRender` 参数。参数是一个对象：
+
 -   routes，路由配置信息
 -   rootElement， 渲染的根节点，默认是 `#app`，可通过配置 `mountElementId` 修改。
 -   initialState， 初始化数据，`beforeRender` 运行得到的数据。

 比如在微前端里动态修改渲染根节点：
+
 ```js
 let isSubApp = false;
 export function modifyClientRenderOpts(lastOpts) {
@ -125,7 +183,8 @@ rootContainer(LastRootContainer, args)
    -   routes，全量路由配置
    -   plugin，运行时插件机制

-比如在可以包一层DIV：
+比如在可以包一层 DIV：
+
 ```js
 export function rootContainer(container) {
    return () => {
@ -133,8 +192,8 @@ export function rootContainer(container) {
            <div>
                <RouterView></RouterView>
            </div>
-        )
-  }
+        );
+    };
 }
 ```

@ -145,14 +204,14 @@ onAppCreated({app})
 创建 app 实例后触发。

 比如用于安装 Vue 插件：
+
 ```js
-import { createRouter } from "vue-router";
+import { createRouter } from 'vue-router';

 export function onAppCreated({ app }) {
    const router = createRouter();
    app.use(router);
 }
-
 ```

 ### render
@ -163,22 +222,22 @@ render(oldRender: Function)

 比如用于渲染之前做权限校验。

-
-
 ### onRouterCreated

 onRouterCreated({router})

-生成router时触发。
+生成 router 时触发。

 比如用于收集切换路由的记录：
+
 ```js
 export function onRouterCreated({ router }) {
    router.afterEach((to, from) => {
-        console.log(to)
+        console.log(to);
    });
 }
 ```

 ## 更多配置项
+
 Fes.js 允许插件注册运行时配置，如果你使用插件，肯定会在插件里找到更多运行时的配置项。
--- a/docs/zh/reference/config/README.md
+++ b/docs/zh/reference/config/README.md
@ -208,7 +208,7 @@ export default {
 -   默认值： `/`
 -   详情：

-    配置 webpack 的 publicPath。当打包的时候，webpack 会在静态文件路径前面添加 `publicPath` 的值，当你需要修改静态文件地址时，比如使用 CDN 部署，把 `publicPath` 的值设为 CDN 的值就可以。
+    静态资源 publicPath。当打包的时候在静态文件路径前面添加 `publicPath` 的值，当你需要修改静态文件地址时，比如使用 CDN 部署，把 `publicPath` 的值设为 CDN 的值就可以。

 ### router

@ -282,7 +282,7 @@ const defaultTerserOptions = {

    配置 [压缩器 terser 的配置项](https://github.com/terser/terser#minify-options)

-## webpack 构建专属配置
+## webpack 专属配置

 ### analyze

--- a/docs/zh/reference/plugin/plugins/sass.md
+++ b/docs/zh/reference/plugin/plugins/sass.md
@ -1,27 +1,34 @@
 # @fesjs/plugin-sass

-
-
 ## 介绍
-Fes.js 默认只支持 `less`，通过此插件扩展支持 `sass`
+
+Fes.js 默认只支持 `less`，通过此插件扩展支持 `sass`。
+
+::: tip webpack 构建 sass 插件
+如果使用 Vite 构建，直接装 `sass` 依赖即可，不需要安装此插件。
+:::

 ## 启用方式
+
 在 `package.json` 中引入依赖：
+
 ```json
 {
    "dependencies": {
        "@fesjs/fes": "^2.0.0",
        "@fesjs/plugin-sass": "^2.0.0"
-    },
+    }
 }
 ```

 ## global css
-添加 `src/global.scss` 和 `src/global.sass` 为全局CSS入口，添加一些通用样式内容。
+
+添加 `src/global.scss` 和 `src/global.sass` 为全局 CSS 入口，添加一些通用样式内容。

 ## Vue 单文件组件
+
 Vue 单文件组件的 `<style></style>` 添加 `lang='scss'`，例如：
+
 ```vue
-<style lang="scss">
-</style>
+<style lang="scss"></style>
 ```
--- a/packages/fes-build-vite/package.json
+++ b/packages/fes-build-vite/package.json
@ -29,6 +29,7 @@
    "@vitejs/plugin-vue": "^2.2.4",
    "@vitejs/plugin-vue-jsx": "^1.3.8",
    "autoprefixer": "^10.4.4",
+    "less": "^4.1.2",
    "postcss-flexbugs-fixes": "^5.0.2",
    "postcss-safe-parser": "^6.0.0",
    "rollup-plugin-visualizer": "^5.6.0",
--- a/packages/fes-build-webpack/src/plugins/registerType.js
+++ b/packages/fes-build-webpack/src/plugins/registerType.js
@ -1,4 +1,4 @@
-import { name } from '../package.json';
+import { name } from '../../package.json';

 export default function (api) {
    api.addConfigType(() => ({
--- a/packages/fes-preset-built-in/src/plugins/features/targets.js
+++ b/packages/fes-preset-built-in/src/plugins/features/targets.js
@ -5,7 +5,7 @@ export default (api) => {
            default: {
                chrome: 56,
                firefox: 67,
-                safari: 10.4,
+                safari: 10,
                edge: 13,
            },
            schema(joi) {
--- a/packages/fes-preset-built-in/src/plugins/generateFiles/core/plugin/pluginRegister.tpl
+++ b/packages/fes-preset-built-in/src/plugins/generateFiles/core/plugin/pluginRegister.tpl
@ -8,7 +8,7 @@ const defaultKey = 'default';

 {{#plugins}}
  plugin.register({
-    apply: Plugin_{{{ index }}}[defaultKey] ? Plugin_{{{ index }}}[defaultKey] : Plugin_{{{ index }}},
+    apply: {...Plugin_{{{ index }}}[defaultKey], ...Plugin_{{{ index }}}},
    path: '{{{ path }}}',
  });
 {{/plugins}}
--- a/yarn.lock
+++ b/yarn.lock
@ -5094,6 +5094,13 @@ cookie@0.4.2, cookie@^0.4.2:
  resolved "https://registry.npmmirror.com/cookie/-/cookie-0.4.2.tgz#0e41f24de5ecf317947c82fc789e06a884824432"
  integrity sha512-aSWTXFzaKWkvHO1Ny/s+ePFpvKsPnjc551iI41v3ny/ow6tBG5Vd+FuqGNhh1LxOmVzOlGUriIlOaokOvhaStA==

+copy-anything@^2.0.1:
+  version "2.0.6"
+  resolved "https://registry.npmmirror.com/copy-anything/-/copy-anything-2.0.6.tgz#092454ea9584a7b7ad5573062b2a87f5900fc480"
+  integrity sha512-1j20GZTsvKNkc4BY3NpMOM8tt///wY3FpIzozTOFO2ffuZcV61nojHXVKIy3WM+7ADCy5FVhdZYHYDdgTU0yJw==
+  dependencies:
+    is-what "^3.14.1"
+
 copy-descriptor@^0.1.0:
  version "0.1.1"
  resolved "https://registry.npmmirror.com/copy-descriptor/-/copy-descriptor-0.1.1.tgz#676f6eb3c39997c2ee1ac3a924fd6124748f578d"
@ -5428,7 +5435,7 @@ debug@4, debug@^4.1.0, debug@^4.1.1, debug@^4.2.0, debug@^4.3.1, debug@^4.3.2, d
  dependencies:
    ms "2.1.2"

-debug@^3.1.1, debug@^3.2.7:
+debug@^3.1.1, debug@^3.2.6, debug@^3.2.7:
  version "3.2.7"
  resolved "https://registry.npmmirror.com/debug/-/debug-3.2.7.tgz#72580b7e9145fb39b6676f9c5e5fb100b934179a"
  integrity sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==
@ -7616,7 +7623,7 @@ husky@^4.3.0:
    slash "^3.0.0"
    which-pm-runs "^1.0.0"

-iconv-lite@0.4.24, iconv-lite@^0.4.24:
+iconv-lite@0.4.24, iconv-lite@^0.4.24, iconv-lite@^0.4.4:
  version "0.4.24"
  resolved "https://registry.npmmirror.com/iconv-lite/-/iconv-lite-0.4.24.tgz#2022b4b25fbddc21d2f524974a474aafe733908b"
  integrity sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==
@ -8174,6 +8181,11 @@ is-weakref@^1.0.2:
  dependencies:
    call-bind "^1.0.2"

+is-what@^3.14.1:
+  version "3.14.1"
+  resolved "https://registry.npmmirror.com/is-what/-/is-what-3.14.1.tgz#e1222f46ddda85dead0fd1c9df131760e77755c1"
+  integrity sha512-sNxgpk9793nzSs7bA6JQJGeIuRBQhAaNGG77kzYQgMkrID+lS6SlK07K5LaptscDlSaIgH+GPFzf+d75FVxozA==
+
 is-windows@^1.0.1, is-windows@^1.0.2:
  version "1.0.2"
  resolved "https://registry.npmmirror.com/is-windows/-/is-windows-1.0.2.tgz#d1850eb9791ecd18e6182ce12a30f396634bb19d"
@ -8960,6 +8972,23 @@ less@3.9.0:
    request "^2.83.0"
    source-map "~0.6.0"

+less@^4.1.2:
+  version "4.1.2"
+  resolved "https://registry.npmmirror.com/less/-/less-4.1.2.tgz#6099ee584999750c2624b65f80145f8674e4b4b0"
+  integrity sha512-EoQp/Et7OSOVu0aJknJOtlXZsnr8XE8KwuzTHOLeVSEx8pVWUICc8Q0VYRHgzyjX78nMEyC/oztWFbgyhtNfDA==
+  dependencies:
+    copy-anything "^2.0.1"
+    parse-node-version "^1.0.1"
+    tslib "^2.3.0"
+  optionalDependencies:
+    errno "^0.1.1"
+    graceful-fs "^4.1.2"
+    image-size "~0.5.0"
+    make-dir "^2.1.0"
+    mime "^1.4.1"
+    needle "^2.5.2"
+    source-map "~0.6.0"
+
 leven@^3.1.0:
  version "3.1.0"
  resolved "https://registry.npmmirror.com/leven/-/leven-3.1.0.tgz#77891de834064cccba82ae7842bb6b14a13ed7f2"
@ -9790,6 +9819,15 @@ natural-compare@^1.4.0:
  resolved "https://registry.npmmirror.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7"
  integrity sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==

+needle@^2.5.2:
+  version "2.9.1"
+  resolved "https://registry.npmmirror.com/needle/-/needle-2.9.1.tgz#22d1dffbe3490c2b83e301f7709b6736cd8f2684"
+  integrity sha512-6R9fqJ5Zcmf+uYaFgdIHmLwNldn5HbK8L5ybn7Uz+ylX/rnOsSp1AHcvQSrCaFN+qNM1wpymHqD7mVasEOlHGQ==
+  dependencies:
+    debug "^3.2.6"
+    iconv-lite "^0.4.4"
+    sax "^1.2.4"
+
 negotiator@0.6.3, negotiator@^0.6.2:
  version "0.6.3"
  resolved "https://registry.npmmirror.com/negotiator/-/negotiator-0.6.3.tgz#58e323a72fedc0d6f9cd4d31fe49f51479590ccd"
@ -10472,6 +10510,11 @@ parse-json@^5.0.0, parse-json@^5.2.0:
    json-parse-even-better-errors "^2.3.0"
    lines-and-columns "^1.1.6"

+parse-node-version@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.npmmirror.com/parse-node-version/-/parse-node-version-1.0.1.tgz#e2b5dbede00e7fa9bc363607f53327e8b073189b"
+  integrity sha512-3YHlOa/JgH6Mnpr05jP9eDG254US9ek25LyIxZlDItp2iJtwyaXQb57lBYLdT3MowkUFYEV2XXNAYIPlESvJlA==
+
 parse-passwd@^1.0.0:
  version "1.0.0"
  resolved "https://registry.npmmirror.com/parse-passwd/-/parse-passwd-1.0.0.tgz#6d5b934a456993b23d37f40a382d6f1666a8e5c6"
@ -11772,6 +11815,11 @@ sass@^1.49.10:
    immutable "^4.0.0"
    source-map-js ">=0.6.2 <2.0.0"

+sax@^1.2.4:
+  version "1.2.4"
+  resolved "https://registry.npmmirror.com/sax/-/sax-1.2.4.tgz#2816234e2378bddc4e5354fab5caa895df7100d9"
+  integrity sha512-NqVDv9TpANUjFm0N8uM5GxL36UgKi9/atZw+x7YFnQ8ckwFGKrl4xX4yWtrey3UJm5nP1kUbnYgLopqWNSRhWw==
+
 saxes@^5.0.1:
  version "5.0.1"
  resolved "https://registry.npmmirror.com/saxes/-/saxes-5.0.1.tgz#eebab953fa3b7608dbe94e5dadb15c888fa6696d"
@ -12983,7 +13031,7 @@ tslib@^1.10.0, tslib@^1.9.0:
  resolved "https://registry.npmmirror.com/tslib/-/tslib-1.14.1.tgz#cf2d38bdc34a134bcaf1091c41f6619e2f672d00"
  integrity sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==

-tslib@^2.0.3, tslib@^2.1.0:
+tslib@^2.0.3, tslib@^2.1.0, tslib@^2.3.0:
  version "2.3.1"
  resolved "https://registry.npmmirror.com/tslib/-/tslib-2.3.1.tgz#e8a335add5ceae51aa261d32a490158ef042ef01"
  integrity sha512-77EbyPPpMz+FRFRuAFlWMtmgUWGe9UOG2Z25NqCwiIjRhOf5iKGuzSe5P2w1laq+FkRy4p+PCuVkJSGkzTEKVw==