diff --git a/AGENTS.md b/AGENTS.md index 9bbc62d..d2c9f46 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,11 @@ pnpm --filter rstack test - Run `pnpm build` once before `pnpm test` command +## Documentation + +- Keep corresponding content in `website/docs/en` and `website/docs/zh` aligned in structure, meaning, links, and examples. +- Keep corresponding heading anchors identical between `website/docs/en` and `website/docs/zh`. When a translated heading would generate a different anchor, add an explicit anchor matching the English heading, for example `## 配置 \{#configuration}`. + ## Project structure ```text diff --git a/website/docs/en/guide/cli/dev.mdx b/website/docs/en/guide/cli/dev.mdx index b6ea4f8..863e087 100644 --- a/website/docs/en/guide/cli/dev.mdx +++ b/website/docs/en/guide/cli/dev.mdx @@ -1,7 +1,43 @@ # dev -TODO. +The `rs dev` command starts the [Rsbuild development server](https://rsbuild.rs/guide/basic/server) for an application. It compiles the source code in development mode, watches for changes, and applies hot module replacement (HMR) or reloads the page as needed. + +## Usage + +```bash +rs dev [options] +``` + +The command loads the application configuration registered with [`define.app()`](../configuration#define-app). When the Rstack configuration file or one of its imported dependencies changes, Rstack automatically restarts the development server and applies the updated configuration. + +## Options + +`rs dev` supports the same development server options as Rsbuild. See the [Rsbuild CLI documentation](https://rsbuild.rs/guide/basic/cli#rsbuild) for details. + +Examples: + +```bash +# Start the server and open the page in the browser +rs dev --open + +# Use port 8080 and fail if it is already in use +rs dev --port 8080 --strict-port + +# Make the server available on the local network +rs dev --host +``` ## Configuration -See [`define.app()`](../configuration#define-app). +Configure the development server through [`define.app()`](../configuration#define-app) in the [Rstack configuration file](/guide/configuration#configuration-file). It accepts the standard [Rsbuild configuration](https://rsbuild.rs/config/): + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + server: { + open: true, + port: 8080, + }, +}); +``` diff --git a/website/docs/zh/guide/cli/build.mdx b/website/docs/zh/guide/cli/build.mdx index 9320eff..02ac929 100644 --- a/website/docs/zh/guide/cli/build.mdx +++ b/website/docs/zh/guide/cli/build.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.app()`](../configuration#define-app)。 diff --git a/website/docs/zh/guide/cli/dev.mdx b/website/docs/zh/guide/cli/dev.mdx index 67f0877..fb12696 100644 --- a/website/docs/zh/guide/cli/dev.mdx +++ b/website/docs/zh/guide/cli/dev.mdx @@ -1,7 +1,43 @@ # dev -TODO. +`rs dev` 命令用于启动应用的 [Rsbuild 开发服务器](https://rsbuild.rs/guide/basic/server)。它会以开发模式编译源码、监听文件变化,并按需进行模块热更新(HMR)或刷新页面。 -## 配置 +## 用法 \{#usage} -参见 [`define.app()`](../configuration#define-app)。 +```bash +rs dev [options] +``` + +该命令会加载通过 [`define.app()`](../configuration#define-app) 注册的应用配置。当 Rstack 配置文件或其导入的任一依赖发生变化时,Rstack 会自动重启开发服务器并应用更新后的配置。 + +## 选项 \{#options} + +`rs dev` 支持与 Rsbuild 相同的开发服务器选项,具体说明请参见 [Rsbuild CLI 文档](https://rsbuild.rs/zh/guide/basic/cli#rsbuild)。 + +示例: + +```bash +# 启动服务器并在浏览器中打开页面 +rs dev --open + +# 使用 8080 端口,并在端口已被占用时退出 +rs dev --port 8080 --strict-port + +# 允许通过局域网访问开发服务器 +rs dev --host +``` + +## 配置 \{#configuration} + +在 [Rstack 配置文件](/guide/configuration#configuration-file)中通过 [`define.app()`](../configuration#define-app) 配置开发服务器。该 API 支持标准的 [Rsbuild 配置](https://rsbuild.rs/zh/config/): + +```ts title="rstack.config.ts" +import { define } from 'rstack'; + +define.app({ + server: { + open: true, + port: 8080, + }, +}); +``` diff --git a/website/docs/zh/guide/cli/doc.mdx b/website/docs/zh/guide/cli/doc.mdx index 33c457b..eee8a23 100644 --- a/website/docs/zh/guide/cli/doc.mdx +++ b/website/docs/zh/guide/cli/doc.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.doc()`](../configuration#define-doc)。 diff --git a/website/docs/zh/guide/cli/lib.mdx b/website/docs/zh/guide/cli/lib.mdx index 31a0247..a307da1 100644 --- a/website/docs/zh/guide/cli/lib.mdx +++ b/website/docs/zh/guide/cli/lib.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.lib()`](../configuration#define-lib)。 diff --git a/website/docs/zh/guide/cli/lint.mdx b/website/docs/zh/guide/cli/lint.mdx index 1303a4b..4b8c288 100644 --- a/website/docs/zh/guide/cli/lint.mdx +++ b/website/docs/zh/guide/cli/lint.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.lint()`](../configuration#define-lint)。 diff --git a/website/docs/zh/guide/cli/preview.mdx b/website/docs/zh/guide/cli/preview.mdx index ba8db6c..c34121a 100644 --- a/website/docs/zh/guide/cli/preview.mdx +++ b/website/docs/zh/guide/cli/preview.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.app()`](../configuration#define-app)。 diff --git a/website/docs/zh/guide/cli/staged.mdx b/website/docs/zh/guide/cli/staged.mdx index af04032..52d56c2 100644 --- a/website/docs/zh/guide/cli/staged.mdx +++ b/website/docs/zh/guide/cli/staged.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.staged()`](../configuration#define-staged)。 diff --git a/website/docs/zh/guide/cli/test.mdx b/website/docs/zh/guide/cli/test.mdx index 20582a5..09ee812 100644 --- a/website/docs/zh/guide/cli/test.mdx +++ b/website/docs/zh/guide/cli/test.mdx @@ -2,6 +2,6 @@ TODO. -## 配置 +## 配置 \{#configuration} 参见 [`define.test()`](../configuration#define-test)。 diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx index f00a463..5cb6c22 100644 --- a/website/docs/zh/guide/configuration.mdx +++ b/website/docs/zh/guide/configuration.mdx @@ -1,8 +1,8 @@ -# 配置 +# 配置 \{#configuration} Rstack 将项目所用工具的配置集中到一份文件中。通过 `define.*()` API 定义项目实际需要的配置即可。 -## 配置文件 +## 配置文件 \{#configuration-file} 在项目根目录创建 `rstack.config.ts`,并调用对应的 `define.*()` API: @@ -33,7 +33,7 @@ Rstack 默认会查找使用以下任一文件名的配置文件: rs build --config ./configs/rstack.config.ts ``` -## 按需加载依赖 +## 按需加载依赖 \{#loading-dependencies-on-demand} 每次执行 `rs` 命令时,Rstack 都会加载并执行配置文件,然后只解析当前命令需要的配置函数。 @@ -51,7 +51,7 @@ define.app(async () => { }); ``` -## 配置 API +## 配置 API \{#configuration-apis} 各 API 沿用底层工具的配置格式。使用 Rstack 已重导出的 API 和辅助函数时,推荐从 `rstack/app`、`rstack/lib`、`rstack/test` 和 `rstack/lint` 入口导入。 diff --git a/website/docs/zh/guide/quick-start.mdx b/website/docs/zh/guide/quick-start.mdx index ac48d7b..03240f7 100644 --- a/website/docs/zh/guide/quick-start.mdx +++ b/website/docs/zh/guide/quick-start.mdx @@ -1,8 +1,8 @@ -# 快速上手 +# 快速上手 \{#quick-start} TODO. -## CLI 命令 +## CLI 命令 \{#cli-commands} - [`rs dev`](./cli/dev):TODO。 - [`rs build`](./cli/build):TODO。