@modern-js/main-doc 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @modern-js/main-doc
 
+## 2.19.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.19.0
+
+## 2.18.1
+
+### Patch Changes
+
+- 21c87bf: feat: bump codesmith packages version
+
+  feat: 升级 codesmith 包版本
+
+  - @modern-js/builder-doc@2.18.1
+
 ## 2.18.0
 
 ### Patch Changes

package/docs/en/configure/app/tools/esbuild.mdx

@@ -9,9 +9,9 @@ sidebar_label: esbuild
 
 ## Introduction
 
-[esbuild](https://esbuild.github.io/) is a front-end build tool based on Golang. It has the functions of bundling, compiling and minimizing JavaScript code. Compared with traditional tools, the performance is significantly improved. When minimizing code, compared to webpack's built-in terser minimizer, esbuild has dozens of times better performance.
+import Esbuild from '@modern-js/builder-doc/docs/en/shared/esbuild.md';
 
-Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader and terser for transformation and minification process.
+<Esbuild />
 
 :::tip Recommend using SWC
 We recommend using SWC to transform and minify code rather than esbuild, because SWC supports more syntaxes, provides better code compression, and the compiled code has better compatibility.
@@ -20,7 +20,6 @@ Therefore, we recommend that you use SWC instead of esbuild, please refer to [to
 
 :::
 
-
 ## Configuration
 
 You can set the esbuild compilation behavior through the `tools.esbuild` config.

package/docs/en/configure/app/tools/swc.mdx

@@ -9,9 +9,9 @@ sidebar_label: swc
 
 ## Introduction
 
-[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
 
-Modern.js Builder has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.
+<SWC />
 
 :::tip
 When using Rspack as the bundler, SWC will be used for transpiling and compression by default, so you don't need to install or configure the SWC plugin.

package/docs/en/guides/basic-features/data-fetch.mdx

@@ -341,6 +341,14 @@ export default async (): Promise<ProfileData> => {
 
 4. When run on the server side, the `loader` functions are packaged into a single bundle, so we do not recommend using `__filename` and `__dirname` for server-side code.
 
+### FAQ
+
+1. Relationship between loader and bff functions
+
+In a CSR project, the loader is executed on the client side and the bff function can be called directly from the loader to make a request.
+
+In an SSR project, each loader is also a server-side API, and we recommend using loader instead of the BFF function which http method is `get` to avoid one more layer of forwarding and execution.
+
 ## useLoader(Old)
 
 **`useLoader`** is an API in Modern.js old version. The API is a React Hook specially provided for SSR applications, allowing developers to fetch data in components.

package/docs/en/guides/basic-features/routes.mdx

@@ -367,6 +367,22 @@ To further improve the user experience and reduce time of loading, Modern.js sup
 - `intent`, the value we recommend for most scenarios, will automatically start loading the corresponding resources and the data defined in the data loader when you mouse over the Link, and will automatically unload it when the mouse is moved away. In our tests, even a direct click can reduce the loading time by about 200ms.
 - `render`, when the Link component renders, it will load the corresponding resources and the data defined in the data loader.
 
+#### FAQ
+
+1. What is the difference between using `render` and not split chunks based on routes?
+
+- With `render` you can specify which routes are loaded on the first screen, and you can control the rendering so that Link components are rendered only when they are in the visible area.
+- With `render`, static resources are loaded only when they are idle and do not hog the network with first-screen static resources.
+- When using server side rendering, data is also prefetched.
+
+import Motivation from '@site-docs-en/components/convention-routing-movitation'
+
+<Motivation/>
+
+import Practice from '@site-docs-en/components/routes-practice'
+
+<Practice/>
+
 ## Self-controlled routing
 
 With `src/App.tsx` as the agreed entry, Modern.js will not do additional operations with multiple routes, developers can use the React Router 6 API for development by themselves, for example:

package/docs/en/guides/get-started/glossary.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+---
+
+# Glossary
+
+## BFF
+
+BFF stands for "Backend For Frontend". It is an architectural pattern where a dedicated backend service is created for frontend applications.
+
+The BFF service acts as an intermediary between the frontend application and the backend APIs, providing a tailored API for the frontend to consume. This allows the frontend developers to have more control over the data and functionality that they need, without having to rely on a monolithic backend API to provide coresponding capabilities.
+
+## Bundler
+
+import Bundler from '@modern-js/builder-doc/docs/en/shared/bundler.md';
+
+<Bundler />
+
+## Builder
+
+import Builder from '@modern-js/builder-doc/docs/en/shared/builder.md';
+
+<Builder />
+
+## CSR
+
+CSR stands for "Client-Side Rendering". It means that pages are rendered directly in the browser using JavaScript. All the logic, data fetching, templating and routing is done on the client rather than the server.
+
+In CSR, the server sends an empty HTML shell to the client along with some JavaScript bundles, which then fetches data from the server's APIs and populates the page with dynamic content.
+
+## Garfish
+
+[Garfish](https://garfish.bytedance.net/) is a set of micro front-end solutions mainly used to solve problems such as cross-team collaboration and technical system diversification of web applications.
+
+Starting from the architectural level, it integrates several independently delivered front-end applications. These front-end applications can be developed, tested and deployed independently, but from the user's point of view they are still a cohesive single product.
+
+## Rspack
+
+import Rspack from '@modern-js/builder-doc/docs/en/shared/rspack.md';
+
+<Rspack />
+
+## SSR
+
+SSR stands for "Server-Side Rendering". It is a technique where the server generates the HTML of a web page and sends it to the client, instead of sending just an empty HTML shell and relying on JavaScript to populate the page.
+
+In traditional client-side rendering, the server sends an empty HTML shell to the client along with some JavaScript bundles, which then fetches data from the server's APIs and populates the page with dynamic content. This can result in a slower initial load time, which can be detrimental to user experience and SEO.
+
+With SSR, the server generates the HTML with the dynamic content already populated, and sends it to the client. This can result in a faster initial load time and better SEO, as search engines can crawl the fully rendered page.
+
+## SSG
+
+SSG stands for "Static Site Generation". It is a technique where a web page is pre-rendered into static HTML, and then served directly to the client without the need for a server to generate the HTML on the fly.
+
+In traditional SSR, the server generates the HTML on the fly each time a user requests a page. With SSG, the HTML is generated ahead of time during the build process and can be served directly from a CDN or other static hosting service.
+
+SSG can provide faster load times and less server overhead to traditional SSR, as there is no need to maintain a server to generate the HTML on the fly. However, it is not suitable for websites that require dynamic content, as the HTML is generated during the build process and cannot be updated in real-time.
+
+## SWC
+
+import SWC from '@modern-js/builder-doc/docs/en/shared/swc.md';
+
+<SWC />

package/docs/en/guides/topic-detail/generator/plugin/api/input/type.mdx

@@ -34,7 +34,7 @@ Each option supports two fields:
 
 - label: display name.
 
-### x-validate
+### x-validator
 
 schema verification rules. Formily's verification method is supported here, for details, please refer to [Formily Validate](https://formilyjs.org/zh-CN/guide/advanced/validate).
 

package/docs/zh/configure/app/tools/esbuild.mdx

@@ -9,9 +9,9 @@ sidebar_label: esbuild
 
 ## 介绍
 
-[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，相比 webpack 内置的 terser 压缩器，esbuild 在性能上有数十倍的提升。
+import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
 
-Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。在大型工程中开启后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
+<Esbuild />
 
 :::tip 推荐使用 SWC
 相较于 esbuild，我们更推荐使用 SWC 来编译和压缩代码，因为 SWC 支持更多的语法特性、拥有更好的代码压缩率，并且产物具备更好的兼容性。

package/docs/zh/configure/app/tools/swc.mdx

@@ -9,9 +9,9 @@ sidebar_label: swc
 
 ## 介绍
 
-[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且比 Babel 性能高出 10 倍不止。
+import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
 
-Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供语法降级、Polyfill 以及压缩，并且移植了一些额外常见的 Babel 插件。
+<SWC />
 
 :::tip
 在使用 Rspack 作为打包工具时，默认会使用 SWC 进行转译和压缩，因此你不需要再安装和配置 SWC 插件。

package/docs/zh/guides/basic-features/data-fetch.mdx

@@ -339,6 +339,15 @@ export default async (): Promise<ProfileData> => {
 
 4. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
 
+### 常见问题
+
+1. loader 和 bff 函数的关系
+
+在 CSR 项目中，loader 在客户端执行，在 loader 可以直接调用 bff 函数进行接口请求。
+
+在 SSR 项目中，每个 loader 也是一个服务端接口，我们推荐使用 loader 替代 http method 为 `get` 的 BFF 函数，作为接口层，避免多一层转发和执行。
+
+
 ## useLoader（旧版）
 
 **`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。

package/docs/zh/guides/basic-features/routes.mdx

@@ -444,7 +444,7 @@ export const init = (context: RuntimeContext) => {
 };
 ```
 
-### Prefetch
+### 预加载
 
 在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片，当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
 这种情况下你可以通过定义 `loading` 组件，在静态资源加载完成前，展示一个自定义的 `loading` 组件。
@@ -462,9 +462,24 @@ export const init = (context: RuntimeContext) => {
 :::
 
 - `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是直接点击，也能减少大约 200ms 的加载时间。
+- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 data loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
 - `render`，当 Link 组件渲染时，就会加载对应的分片和 data loader 中定义的数据。
 
+#### 常见问题
+
+1. 使用 `render` 和不根据路由做静态资源分片的区别？
+
+- 使用 `render` 可以指定哪些路由在首屏时，进行加载，同时你可以通过对渲染的控制，仅当 Link 组件进入到可视区域时，才对 Link 组件进行渲染。
+- 使用 `render`，仅在空闲时对静态资源进行加载，不会与首屏静态资源抢占网络。
+- 在 SSR 场景下，也会对数据进行预取。
+
+import Motivation from '@site-docs/components/convention-routing-movitation'
+
+<Motivation/>
+
+import Practice from '@site-docs/components/routes-practice'
+
+<Practice/>
 
 
 ## 自控式路由

package/docs/zh/guides/get-started/glossary.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+---
+
+# 名词解释
+
+## BFF
+
+BFF 是 "Backend For Frontend"（前端的后端） 的缩写。它是一种架构模式，表示为前端应用程序创建一个专门的后台服务。
+
+BFF 服务作为前端应用程序和服务端 API 之间的中介，可以为前端提供定制的 API 供其使用。这允许前端开发者对需要的数据和功能有更多的控制，而不必依赖后端服务提供相应的能力。
+
+## Bundler
+
+import Bundler from '@modern-js/builder-doc/docs/zh/shared/bundler.md';
+
+<Bundler />
+
+## Builder
+
+import Builder from '@modern-js/builder-doc/docs/zh/shared/builder.md';
+
+<Builder />
+
+## CSR
+
+CSR 是 "Client-Side Rendering"（客户端渲染）的缩写。它表示页面是在浏览器中通过 JavaScript 渲染的，数据获取、模板和路由等逻辑都在浏览器端完成，而不是在服务器上。
+
+在 CSR 中，服务器会向浏览器端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后由浏览器端从服务器的 API 中拉取数据，并将动态内容渲染到页面中。
+
+## Garfish
+
+[Garfish](https://garfish.bytedance.net/) 是一套微前端解决方案，主要用于解决 web 应用的跨团队协作、技术体系多样化等问题。
+
+它从架构层面出发，将多个独立交付的前端应用组成整体，这些前端应用能够独立开发、独立测试、独立部署，但是在用户视角仍然是内聚的单个产品。
+
+## Rspack
+
+import Rspack from '@modern-js/builder-doc/docs/zh/shared/rspack.md';
+
+<Rspack />
+
+## SSR
+
+SSR 是 "Server-Side Rendering"（服务器端渲染）的缩写。它表示由服务器生成网页的 HTML，并将其发送给客户端，而不是只发送一个空的 HTML 外壳，并依赖 JavaScript 来生成页面内容。
+
+在传统的客户端渲染中，服务器会向客户端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后从服务器的 API 中获取数据，并用动态内容填充页面。这会导致页面的初始加载时间较慢，不利于用户体验和 SEO。
+
+使用 SSR 后，服务器会生成已经包含动态内容的 HTML，并将其发送给客户端。这使得首屏加载速度更快，并对 SEO 更加友好，因为搜索引擎可以爬取到渲染后的页面。
+
+## SSG
+
+SSG 是 "Static Site Generation"（静态网站生成）的缩写。它表示网页被预先渲染成静态的 HTML，然后直接提供给客户端，而不需要服务器实时生成 HTML。
+
+在传统的 SSR 中，每当用户请求一个页面时，服务器就会实时生成 HTML。有了 SSG，HTML 可以在构建过程中被提前生成，并被托管在 CDN 或其他静态资源服务中。
+
+与传统的 SSR 相比，SSG 可以提供更快的加载速度以及更少的服务端开销，因为不需要维护一个服务器来实时生成 HTML。然而，SSG 不适合需要动态内容的网站，因为 HTML 是在构建过程中生成的，不支持实时更新。
+
+## SWC
+
+import SWC from '@modern-js/builder-doc/docs/zh/shared/swc.md';
+
+<SWC />

package/docs/zh/guides/topic-detail/generator/plugin/api/input/type.mdx

@@ -34,7 +34,7 @@ schema 如果为选择类型，该字段用于定义选项内容。
 
 - label: 展示名称。
 
-### x-validate
+### x-validator
 
 schema 的验证规则。这里支持 Formily 的校验方式，具体可参考 [Formily 表单校验](https://formilyjs.org/zh-CN/guide/advanced/validate)。
 

package/package.json

@@ -15,13 +15,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.18.0",
+  "version": "2.19.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.18.0"
+    "@modern-js/builder-doc": "^2.19.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -33,9 +33,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.18.0",
-    "@modern-js/doc-tools": "2.18.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.18.0"
+    "@modern-js/builder-doc": "2.19.0",
+    "@modern-js/doc-tools": "2.19.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.19.0"
   },
   "scripts": {
     "dev": "modern dev",