From 76e7fcb62999c968f8a734b9c0d5f1f0bbc7225b Mon Sep 17 00:00:00 2001 From: neverland Date: Thu, 12 Sep 2024 19:02:14 +0800 Subject: [PATCH] docs: update outdated glossary (#3464) --- .../docs/en/guide/advanced/environments.mdx | 13 +++++-- website/docs/en/guide/advanced/ssr.mdx | 6 ++-- website/docs/en/guide/basic/cli.mdx | 3 +- website/docs/en/guide/start/glossary.mdx | 35 ++++++------------- website/docs/en/shared/environment.mdx | 12 ------- website/docs/en/shared/ssr.mdx | 5 --- .../docs/zh/guide/advanced/environments.mdx | 13 +++++-- website/docs/zh/guide/advanced/ssr.mdx | 6 ++-- website/docs/zh/guide/basic/cli.mdx | 5 +-- website/docs/zh/guide/start/glossary.mdx | 35 ++++++------------- website/docs/zh/shared/environment.mdx | 12 ------- website/docs/zh/shared/ssr.mdx | 5 --- 12 files changed, 57 insertions(+), 93 deletions(-) delete mode 100644 website/docs/en/shared/environment.mdx delete mode 100644 website/docs/en/shared/ssr.mdx delete mode 100644 website/docs/zh/shared/environment.mdx delete mode 100644 website/docs/zh/shared/ssr.mdx diff --git a/website/docs/en/guide/advanced/environments.mdx b/website/docs/en/guide/advanced/environments.mdx index 64771d0e7a..a739e7788e 100644 --- a/website/docs/en/guide/advanced/environments.mdx +++ b/website/docs/en/guide/advanced/environments.mdx @@ -4,9 +4,18 @@ Rsbuild supports building outputs for multiple environments at the same time. Yo ## What is environment -import Environment from '@en/shared/environment.mdx'; +The `environment` refers to the runtime environment for build output. Common environments include browsers, Node.js, and Workers. Rsbuild allows you to define any environment names and set build options for each environment individually. - +A typical scenario is server-side rendering (SSR). You can define two environments, `web` and `node`, where the build targets ([output.target](/config/output/target)) are `web` and `node`. These are used for client-side rendering (CSR) and server-side rendering (SSR) scenarios. + +You can also define different environments for the same build target, for example: + +- Define `rsc` and `ssr` environments, both targeting `node`, used separately for React Server Components and SSR. +- Define `desktop` and `mobile` environments, both targeting `web`, used separately for desktop and mobile browsers. + +Without the `environments` configuration, you would need to define multiple configurations for these scenarios and run multiple independent Rsbuild builds. Now, with the `environments` configuration, you can complete the build for multiple outputs in a single Rsbuild run (Rsbuild achieves this using Rspack's `MultiCompiler`). + +In Rsbuild, each `environment` is associated with an Rsbuild configuration, an Rspack configuration, and a set of build outputs. Rsbuild plugin developers can customize the build process for a specified environment based on the `environment` name, such as modifying Rsbuild or Rspack configurations, registering or removing plugins, adjusting Rspack rules, and viewing assets information. ## Environment configs diff --git a/website/docs/en/guide/advanced/ssr.mdx b/website/docs/en/guide/advanced/ssr.mdx index c543c44386..6a889bb6e1 100644 --- a/website/docs/en/guide/advanced/ssr.mdx +++ b/website/docs/en/guide/advanced/ssr.mdx @@ -6,9 +6,11 @@ Please note that Rsbuild itself does not provide out-of-the-box SSR functionalit ## What is SSR -import SSR from '@en/shared/ssr.mdx'; +SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content. - +In traditional client-side rendering, the server sends an empty HTML shell and some JavaScript scripts to the client, and then fetching data from the server's API and fills the page with dynamic content. This leads to slow initial page loading times and is not conducive to user experience and SEO. + +With SSR, the server generates HTML that already contains dynamic content and sends it to the client. This makes the initial page loading faster and more SEO-friendly, as search engines can crawl the rendered page. ## File Structure diff --git a/website/docs/en/guide/basic/cli.mdx b/website/docs/en/guide/basic/cli.mdx index 4f03db1449..3afea1020d 100644 --- a/website/docs/en/guide/basic/cli.mdx +++ b/website/docs/en/guide/basic/cli.mdx @@ -171,7 +171,8 @@ If the current project has multiple build targets, such as building browser arti Inspect config succeed, open following files to view the content: - - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs + - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs + - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs ``` diff --git a/website/docs/en/guide/start/glossary.mdx b/website/docs/en/guide/start/glossary.mdx index 3fe02431a3..c953208ebe 100644 --- a/website/docs/en/guide/start/glossary.mdx +++ b/website/docs/en/guide/start/glossary.mdx @@ -2,7 +2,7 @@ ## Bundler -Refers to module bundlers such as [Rspack](https://rspack.dev/) and [Webpack](https://webpack.js.org/). +Refers to module bundlers such as [Rspack](https://rspack.dev/) and [webpack](https://webpack.js.org/). The main goal of bundlers is to bundle JavaScript, CSS and other files together, and the bundled files can be used in the browser, Node.js or other environments. When bundler processes the Web application, it builds a dependency graph and then combines every module into one or more bundles. @@ -14,9 +14,7 @@ In CSR, the server sends an empty HTML shell and some JavaScript scripts to the ## Environment -import Environment from '@en/shared/environment.mdx'; - - +The runtime environment for build output, see [Multi-Environment Builds](/guide/advanced/environments). ## Micro-frontend @@ -29,44 +27,33 @@ It primarily addresses two problems: ## Modern.js -Modern.js is an open source web engineering system from ByteDance, which provides multiple solutions to help developers solve problems in different development scenarios. - -- [Modern.js Repository](https://github.com/web-infra-dev/modern.js). +[Modern.js](https://github.com/web-infra-dev/modern.js) is an open source web engineering system from ByteDance, which provides multiple solutions to help developers solve problems in different development scenarios. ## Module Federation -Module Federation is an architectural pattern for the decentralization of JavaScript applications (similar to microservices on the server-side). It allows you to share code and resources among multiple JavaScript applications (or micro-frontends). This can help you: - -- Reduce code duplication -- Improve code maintainability -- Lower the overall size of your applications -- Enhance the performance of your applications +Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends). -Please refer to [Module Federation guide](/guide/advanced/module-federation) for details. +See [Module Federation](/guide/advanced/module-federation) for more details. ## Rspack -[Rspack](https://rspack.dev/) is a high performance JavaScript bundler based on Rust, with interoperability with the webpack ecosystem, allowing it to be integrated into webpack projects at a low cost while providing better build performance. - -Compared to webpack, Rspack has significantly improved build performance, thanks not only to the language advantages brought by Rust, but also to its parallel architecture and incremental compilation features. Benchmarking has shown that Rspack can provide 5-10 times better compilation performance. +[Rspack](https://rspack.dev/) is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds. ## Rspress -Rspress is a fast static site generator based on Rsbuild. - -- [Rspress Repository](https://github.com/web-infra-dev/rspress). +[Rspress](https://github.com/web-infra-dev/rspress) is a fast static site generator based on Rsbuild. ## SSR -import SSR from '@en/shared/ssr.mdx'; +SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content. - +See [Server-Side Rendering (SSR)](/guide/advanced/ssr) for more details. ## SWC -SWC (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. +SWC (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on Rust. -Rsbuild supports SWC by default, power your web application with polyfill and minification. +See [Configure SWC](/guide/basic/configure-swc) for more details. ## More diff --git a/website/docs/en/shared/environment.mdx b/website/docs/en/shared/environment.mdx deleted file mode 100644 index 1b994bb549..0000000000 --- a/website/docs/en/shared/environment.mdx +++ /dev/null @@ -1,12 +0,0 @@ -The `environment` refers to the runtime environment for build output. Common environments include browsers, Node.js, and Workers. Rsbuild allows you to define any environment names and set build options for each environment individually. - -A typical scenario is server-side rendering (SSR). You can define two environments, `web` and `node`, where the build targets ([output.target](/config/output/target)) are `web` and `node`. These are used for client-side rendering (CSR) and server-side rendering (SSR) scenarios. - -You can also define different environments for the same build target, for example: - -- Define `rsc` and `ssr` environments, both targeting `node`, used separately for React Server Components and SSR. -- Define `desktop` and `mobile` environments, both targeting `web`, used separately for desktop and mobile browsers. - -Without the `environments` configuration, you would need to define multiple configurations for these scenarios and run multiple independent Rsbuild builds. Now, with the `environments` configuration, you can complete the build for multiple outputs in a single Rsbuild run (Rsbuild achieves this using Rspack's `MultiCompiler`). - -In Rsbuild, each `environment` is associated with an Rsbuild configuration, an Rspack configuration, and a set of build outputs. Rsbuild plugin developers can customize the build process for a specified environment based on the `environment` name, such as modifying Rsbuild or Rspack configurations, registering or removing plugins, adjusting Rspack rules, and viewing assets information. diff --git a/website/docs/en/shared/ssr.mdx b/website/docs/en/shared/ssr.mdx deleted file mode 100644 index 1be1af43f5..0000000000 --- a/website/docs/en/shared/ssr.mdx +++ /dev/null @@ -1,5 +0,0 @@ -SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content. - -In traditional client-side rendering, the server sends an empty HTML shell and some JavaScript scripts to the client, and then fetching data from the server's API and fills the page with dynamic content. This leads to slow initial page loading times and is not conducive to user experience and SEO. - -With SSR, the server generates HTML that already contains dynamic content and sends it to the client. This makes the initial page loading faster and more SEO-friendly, as search engines can crawl the rendered page. diff --git a/website/docs/zh/guide/advanced/environments.mdx b/website/docs/zh/guide/advanced/environments.mdx index 7c7f140621..27309812ba 100644 --- a/website/docs/zh/guide/advanced/environments.mdx +++ b/website/docs/zh/guide/advanced/environments.mdx @@ -4,9 +4,18 @@ Rsbuild 支持同时为多个环境构建产物。你可以使用 [environments] ## 什么是 environment -import Environment from '@zh/shared/environment.mdx'; +`environment` 指的是构建产物的运行环境，常见的运行环境有浏览器、Node.js 和 Workers。Rsbuild 允许你定义任意的 environment 名称，并为这些 environment 分别设置构建选项。 - +一个典型的场景是服务器端渲染（SSR），你可以定义 `web` 和 `node` 两个 environments，它们的构建目标（[output.target](/config/output/target)）分别是 `web` 和 `node`，并用于客户端渲染（CSR）和服务器端渲染（SSR）场景。 + +此外，你还可以为同一个构建目标定义不同的 environment，例如： + +- 定义 `rsc` 和 `ssr` 两个环境，它们的构建目标都是 `node`，分别用于 React Server Components 和 SSR。 +- 定义 `desktop` 和 `mobile` 两个环境，它们的构建目标都是 ` web`，分别用于桌面端浏览器和移动端浏览器。 + +如果没有 `environments` 配置，你需要为这些场景定义多份配置，并执行多次独立的 Rsbuild 构建。现在通过 `environments` 配置，你可以在一次 Rsbuild 构建中完成多种产物的构建（Rsbuild 基于 Rspack 的 `MultiCompiler` 来实现这一点）。 + +Rsbuild 中的每个 `environment` 关联一份 Rsbuild 配置、一份 Rspack 配置和一份构建产物。Rsbuild 插件的开发者可以基于 `environment` 名称，对指定环境的构建流程进行定制，如修改 Rsbuild 或 Rspack 配置、注册或移除插件、调整 Rspack 规则和查看静态资源信息等。 ## 多环境配置 diff --git a/website/docs/zh/guide/advanced/ssr.mdx b/website/docs/zh/guide/advanced/ssr.mdx index c8f19a5b96..747cda5090 100644 --- a/website/docs/zh/guide/advanced/ssr.mdx +++ b/website/docs/zh/guide/advanced/ssr.mdx @@ -6,9 +6,11 @@ ## 什么是 SSR -import SSR from '@zh/shared/ssr.mdx'; +SSR 是 "Server-Side Rendering"（服务端渲染）的缩写。它表示由服务器生成网页的 HTML，并将其发送给客户端，而不是只发送一个空的 HTML 外壳，并依赖 JavaScript 来生成页面内容。 - +在传统的客户端渲染中，服务器会向客户端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后从服务器的 API 中获取数据，并用动态内容填充页面。这会导致页面的初始加载时间较慢，不利于用户体验和 SEO。 + +使用 SSR 后，服务器会生成已经包含动态内容的 HTML，并将其发送给客户端。这使得首屏加载速度更快，并对 SEO 更加友好，因为搜索引擎可以爬取到渲染后的页面。 ## 文件结构 diff --git a/website/docs/zh/guide/basic/cli.mdx b/website/docs/zh/guide/basic/cli.mdx index b3852cc8ea..21a0e71e39 100644 --- a/website/docs/zh/guide/basic/cli.mdx +++ b/website/docs/zh/guide/basic/cli.mdx @@ -10,7 +10,7 @@ Rsbuild 内置了一个轻量的命令行工具，包含 dev、build 等命令 npx rsbuild -h ``` -The output is as follows: +输出如下： ```text Usage: rsbuild [options] @@ -171,7 +171,8 @@ rsbuild inspect --verbose Inspect config succeed, open following files to view the content: - - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs + - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs + - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs ``` diff --git a/website/docs/zh/guide/start/glossary.mdx b/website/docs/zh/guide/start/glossary.mdx index 7214a7b081..fbe25dd1a0 100644 --- a/website/docs/zh/guide/start/glossary.mdx +++ b/website/docs/zh/guide/start/glossary.mdx @@ -2,7 +2,7 @@ ## Bundler -指 [Rspack](https://rspack.dev/)、[Webpack](https://webpack.js.org/) 等模块打包工具。 +指 [Rspack](https://rspack.dev/)、[webpack](https://webpack.js.org/) 等模块打包工具。 打包工具的主要目标是将 JavaScript、CSS 等文件打包在一起，打包后的文件可以在浏览器、Node.js 等环境中使用。当 Bundler 处理 Web 应用时，它会构建一个依赖关系图，其中包含应用需要的各个模块，然后将所有模块打包成一个或多个 bundle。 @@ -14,9 +14,7 @@ CSR 是 "Client-Side Rendering"（客户端渲染）的缩写。它表示页面 ## Environment -import Environment from '@zh/shared/environment.mdx'; - - +`environment` 指的是构建产物的运行环境，详见 [多环境构建](/guide/advanced/environments)。 ## Micro-frontend @@ -29,44 +27,33 @@ import Environment from '@zh/shared/environment.mdx'; ## Modern.js -Modern.js 是字节跳动 Web 工程体系的开源版本，它提供多个解决方案，来帮助开发者解决不同研发场景下的问题。 - -- [Modern.js 代码仓库](https://github.com/web-infra-dev/modern.js)。 +[Modern.js](https://github.com/web-infra-dev/modern.js) 是一个基于 Rsbuild 实现的渐进式 Web 开发框架。 ## Module Federation -Module Federation 是一种 JavaScript 应用分治的架构模式（类似于服务端的微服务），它允许你在多个 JavaScript 应用程序（或微前端）之间共享代码和资源。这可以帮助你： - -- 减少代码重复 -- 提高代码可维护性 -- 降低应用程序的整体大小 -- 提高应用程序的性能 +Module Federation 是一种 JavaScript 应用分治的架构模式（类似于服务端的微服务），它允许你在多个 JavaScript 应用程序（或微前端）之间共享代码和资源。 -请参考 [模块联邦指南](/guide/advanced/module-federation) 了解更多。 +详见 [模块联邦](/guide/advanced/module-federation)。 ## Rspack -[Rspack](https://rspack.dev/) 是一个基于 Rust 的高性能 Web 构建工具，具备与 webpack 生态系统的互操作性，可以被 webpack 项目低成本集成，并提供更好的构建性能。 - -相较于 webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，Rspack 可以带来 5 ～ 10 倍编译性能的提升。 +[Rspack](https://rspack.dev/) 是一个基于 Rust 编写的高性能 JavaScript 打包工具， 它提供对 webpack 生态良好的兼容性，能够无缝替换 webpack， 并提供闪电般的构建速度。 ## Rspress -Rspress 是一个基于 Rsbuild 的静态站点生成器。 - -- [Rspress 代码仓库](https://github.com/web-infra-dev/rspress)。 +[Rspress](https://github.com/web-infra-dev/rspress) 是一个基于 Rsbuild 的静态站点生成器。 ## SSR -import SSR from '@zh/shared/ssr.mdx'; +SSR 是 "Server-Side Rendering"（服务端渲染）的缩写。它表示由服务器生成网页的 HTML，并将其发送给客户端，而不是只发送一个空的 HTML 外壳，并依赖 JavaScript 来生成页面内容。 - +详见 [服务端渲染（SSR）](/guide/advanced/ssr)。 ## SWC -SWC (Speedy Web Compiler) 是基于 Rust 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且性能比 Babel 高出一个数量级。 +SWC (Speedy Web Compiler) 是基于 Rust 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。 -Rsbuild 默认支持 SWC 编译，可以为你的 web 应用提供语法降级、polyfill 以及代码压缩。 +详见 [配置 SWC](/guide/basic/configure-swc)。 ## 更多 diff --git a/website/docs/zh/shared/environment.mdx b/website/docs/zh/shared/environment.mdx deleted file mode 100644 index 0930e3d60e..0000000000 --- a/website/docs/zh/shared/environment.mdx +++ /dev/null @@ -1,12 +0,0 @@ -`environment` 指的是构建产物的运行环境，常见的运行环境有浏览器、Node.js 和 Workers。Rsbuild 允许你定义任意的 environment 名称，并为这些 environment 分别设置构建选项。 - -一个典型的场景是服务器端渲染（SSR），你可以定义 `web` 和 `node` 两个 environments，它们的构建目标（[output.target](/config/output/target)）分别是 `web` 和 `node`，并用于客户端渲染（CSR）和服务器端渲染（SSR）场景。 - -此外，你还可以为同一个构建目标定义不同的 environment，例如： - -- 定义 `rsc` 和 `ssr` 两个环境，它们的构建目标都是 `node`，分别用于 React Server Components 和 SSR。 -- 定义 `desktop` 和 `mobile` 两个环境，它们的构建目标都是 ` web`，分别用于桌面端浏览器和移动端浏览器。 - -如果没有 `environments` 配置，你需要为这些场景定义多份配置，并执行多次独立的 Rsbuild 构建。现在通过 `environments` 配置，你可以在一次 Rsbuild 构建中完成多种产物的构建（Rsbuild 基于 Rspack 的 `MultiCompiler` 来实现这一点）。 - -Rsbuild 中的每个 `environment` 关联一份 Rsbuild 配置、一份 Rspack 配置和一份构建产物。Rsbuild 插件的开发者可以基于 `environment` 名称，对指定环境的构建流程进行定制，如修改 Rsbuild 或 Rspack 配置、注册或移除插件、调整 Rspack 规则和查看静态资源信息等。 diff --git a/website/docs/zh/shared/ssr.mdx b/website/docs/zh/shared/ssr.mdx deleted file mode 100644 index f65ea728bf..0000000000 --- a/website/docs/zh/shared/ssr.mdx +++ /dev/null @@ -1,5 +0,0 @@ -SSR 是 "Server-Side Rendering"（服务端渲染）的缩写。它表示由服务器生成网页的 HTML，并将其发送给客户端，而不是只发送一个空的 HTML 外壳，并依赖 JavaScript 来生成页面内容。 - -在传统的客户端渲染中，服务器会向客户端发送一个空的 HTML 外壳和一些 JavaScript 脚本，然后从服务器的 API 中获取数据，并用动态内容填充页面。这会导致页面的初始加载时间较慢，不利于用户体验和 SEO。 - -使用 SSR 后，服务器会生成已经包含动态内容的 HTML，并将其发送给客户端。这使得首屏加载速度更快，并对 SEO 更加友好，因为搜索引擎可以爬取到渲染后的页面。