From 1f296e19abca2c36690a29f4bb8307fee578d5c6 Mon Sep 17 00:00:00 2001 From: chenjiahan Date: Mon, 25 Dec 2023 16:59:02 +0800 Subject: [PATCH] docs: comparing Rspack dev server --- .../en/config/server/history-api-fallback.mdx | 2 +- .../document/docs/en/guide/basic/_meta.json | 2 +- .../guide/basic/{page-route.md => server.md} | 32 ++++++++++++++----- .../zh/config/server/history-api-fallback.mdx | 2 +- .../document/docs/zh/guide/basic/_meta.json | 4 +-- .../guide/basic/{page-route.md => server.md} | 30 +++++++++++++---- 6 files changed, 52 insertions(+), 20 deletions(-) rename packages/document/docs/en/guide/basic/{page-route.md => server.md} (60%) rename packages/document/docs/zh/guide/basic/{page-route.md => server.md} (63%) diff --git a/packages/document/docs/en/config/server/history-api-fallback.mdx b/packages/document/docs/en/config/server/history-api-fallback.mdx index d3674d6503..4ba009d1a0 100644 --- a/packages/document/docs/en/config/server/history-api-fallback.mdx +++ b/packages/document/docs/en/config/server/history-api-fallback.mdx @@ -3,7 +3,7 @@ - **Type:** `boolean | ConnectHistoryApiFallbackOptions` - **Default:** `false` -When Rsbuild's default [page route](/guide/basic/page-route) logic cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can set it up using `server.historyApiFallback`. +When Rsbuild's default [page routing](/guide/basic/server#page-routing) behavior cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can set it up using `server.historyApiFallback`. ### Example diff --git a/packages/document/docs/en/guide/basic/_meta.json b/packages/document/docs/en/guide/basic/_meta.json index 953a5240e8..ba6b8709ef 100644 --- a/packages/document/docs/en/guide/basic/_meta.json +++ b/packages/document/docs/en/guide/basic/_meta.json @@ -1,7 +1,7 @@ [ "cli", "config", - "page-route", + "server", "output-files", "css-usage", "static-assets", diff --git a/packages/document/docs/en/guide/basic/page-route.md b/packages/document/docs/en/guide/basic/server.md similarity index 60% rename from packages/document/docs/en/guide/basic/page-route.md rename to packages/document/docs/en/guide/basic/server.md index 3021d13a1e..7d5a074966 100644 --- a/packages/document/docs/en/guide/basic/page-route.md +++ b/packages/document/docs/en/guide/basic/server.md @@ -1,8 +1,12 @@ -# Page Route +# Server -This chapter will introduces how to access pages during local development and preview. +Rsbuild comes with a built-in dev server designed to improve the development experience. When you run the `rsbuild dev` or `rsbuild preview` commands, the server will start, providing features such as page preview, routing, and hot module reloading. -## Default +## Page Routing + +Rsbuild Server offers a set of default routing convention, and allows users to customize it through configurations. + +### Default Behavior Rsbuild Server will generate the corresponding page route based on the [source.entry](/config/source/entry) configuration. @@ -19,7 +23,7 @@ export default { }; ``` -## Default fallback logic +### Fallback Behavior By default, when the request meets the following conditions and the corresponding resource is not found, it will fallback to `index.html`: @@ -34,9 +38,9 @@ export default { }; ``` -### Custom fallback logic +### Custom Fallback Behavior -When Rsbuild's default [server.htmlFallback](/config/server/html-fallback) configuration cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can set it up using [server.historyApiFallback] (/config/server/history-api-fallback). +When Rsbuild's default [server.htmlFallback](/config/server/html-fallback) configuration cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can set it up using [server.historyApiFallback](/config/server/history-api-fallback). ```ts title=rsbuild.config.ts export default { @@ -54,7 +58,7 @@ export default { }; ``` -## HTML file output path and Route +### HTML Output Path Normally, `/` points to the dist root directory, and the HTML file is output to the dist root directory. At this time, the corresponding HTML page can be accessed through `/xxx`. @@ -62,7 +66,7 @@ If you output HTML files to other subdirectories by modifying [output.distPath.h For example, if you set the HTML file to be output to the `HTML` directory, index.html will be accessed through `/html/`, and foo.html will be accessed through `/html/foo`. -``` +```ts export default { source: { entry: { @@ -77,3 +81,15 @@ export default { }, }; ``` + +## Comparing Rspack Dev Server + +Rsbuild dev server and the dev server of Rspack CLI (`@rspack/dev-server`) share some similarities and differences: + +- Both are based on [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware). +- They have different configs, with Rsbuild offering a richer set of configurations. +- The log format of Rspack CLI aligns with Webpack CLI, while the logs of Rsbuild are clearer and more readable. + +:::tip +Rsbuild applications cannot use Rspack's [devServer](https://rspack.dev/config/dev-server) config. You can configure the behavior of the server through Rsbuild's `dev` and `server` configs, see [Config Overview](/config/index) for details. +::: diff --git a/packages/document/docs/zh/config/server/history-api-fallback.mdx b/packages/document/docs/zh/config/server/history-api-fallback.mdx index a9efb4ac3c..dc4b1ad646 100644 --- a/packages/document/docs/zh/config/server/history-api-fallback.mdx +++ b/packages/document/docs/zh/config/server/history-api-fallback.mdx @@ -3,7 +3,7 @@ - **类型：** `boolean | ConnectHistoryApiFallbackOptions` - **默认值：** `false` -当 Rsbuild 默认的 [页面路由](/guide/basic/page-route) 逻辑无法满足你的需求时，例如，希望在访问 `/` 时可以访问 `main.html`，可通过 `server.historyApiFallback` 进行设置。 +当 Rsbuild 默认的 [页面路由](/guide/basic/server#page-routing) 行为无法满足你的需求时，例如，希望在访问 `/` 时可以访问 `main.html`，可通过 `server.historyApiFallback` 进行设置。 ### 示例 diff --git a/packages/document/docs/zh/guide/basic/_meta.json b/packages/document/docs/zh/guide/basic/_meta.json index 9b230dd71a..ba6b8709ef 100644 --- a/packages/document/docs/zh/guide/basic/_meta.json +++ b/packages/document/docs/zh/guide/basic/_meta.json @@ -1,7 +1,7 @@ [ - "config", - "page-route", "cli", + "config", + "server", "output-files", "css-usage", "static-assets", diff --git a/packages/document/docs/zh/guide/basic/page-route.md b/packages/document/docs/zh/guide/basic/server.md similarity index 63% rename from packages/document/docs/zh/guide/basic/page-route.md rename to packages/document/docs/zh/guide/basic/server.md index 21e5c5be3e..0a0554f5f0 100644 --- a/packages/document/docs/zh/guide/basic/page-route.md +++ b/packages/document/docs/zh/guide/basic/server.md @@ -1,8 +1,12 @@ -# 页面路由 +# 开发服务器 -本章节介绍了如何在本地开发和预览时进行页面访问。 +Rsbuild 配备了一个内置的开发服务器，旨在提升开发体验。当你执行 `rsbuild dev` 或 `rsbuild preview` 命令时，该服务器将启动，并提供页面预览、路由、模块热更新等功能。 -## 默认情况 +## 页面路由 + +Rsbuild 的 Server 提供一套默认的路由约定，并允许用户通过配置项定制。 + +### 默认行为 Rsbuild Server 会根据 [source.entry](/config/source/entry) 配置生成对应的页面路由。 @@ -19,7 +23,7 @@ export default { }; ``` -## 默认 Fallback 逻辑 +### Fallback 行为 当请求满足以下条件且未找到对应资源时，会被 `server.htmlFallback` 处理，默认会回退到 index.html。 @@ -34,7 +38,7 @@ export default { }; ``` -### 自定义 Fallback 逻辑 +### 自定义 Fallback 行为 当 Rsbuild 默认的 [server.htmlFallback](/config/server/html-fallback) 配置无法满足你的需求，例如，希望在访问 `/` 时可以访问 `main.html`，可通过 [server.historyApiFallback](/config/server/history-api-fallback) 进行设置。 @@ -54,7 +58,7 @@ export default { }; ``` -## HTML 文件输出位置与路由的关系 +### HTML 输出路径 通常情况下，`/` 指向 dist 产物根目录， 而 HTML 文件输出到 dist 根目录下，此时可通过 `/xxx` 访问对应的 HTML 页面。 @@ -62,7 +66,7 @@ export default { 例如，设置将 HTML 文件输出到 `HTML` 目录下，此时将通过 `/html/` 访问到 index.html，通过 `/html/foo` 访问到 foo.html。 -``` +```ts export default { source: { entry: { @@ -77,3 +81,15 @@ export default { }, }; ``` + +## 对比 Rspack Dev Server + +Rsbuild 的开发服务器与 Rspack CLI 的开发服务器（`@rspack/dev-server`）有一些异同： + +- 两者都是基于 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) 实现。 +- 两者的配置项不同，Rsbuild 提供了更丰富的配置项。 +- Rspack CLI 日志格式会与 Webpack CLI 对齐，Rsbuild 的日志则更加清晰和易读。 + +:::tip +Rsbuild 应用不能使用 Rspack 的 [devServer](https://rspack.dev/config/dev-server) 配置项。你可以通过 Rsbuild 的 `dev` 和 `server` 配置 Server 的行为，详见 [Config 总览](/config/index)。 +:::