From 824cc48760d1dcdc08dde33348df9b2ec85bd431 Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Wed, 2 Sep 2026 16:02:01 +0800
Subject: [PATCH] docs: clarify config import guidance

---
 website/docs/en/guide/configuration.mdx | 15 ++++++++++++---
 website/docs/en/guide/monorepo.mdx      |  8 +++-----
 website/docs/zh/guide/configuration.mdx | 15 ++++++++++++---
 website/docs/zh/guide/monorepo.mdx      |  8 +++-----
 4 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/website/docs/en/guide/configuration.mdx b/website/docs/en/guide/configuration.mdx
index d1aaa0aa..e50bb635 100644
--- a/website/docs/en/guide/configuration.mdx
+++ b/website/docs/en/guide/configuration.mdx
@@ -44,11 +44,14 @@ All `rs` commands accept the global `-c, --config` option for loading a file wit
 rs build --config ./configs/rstack.config.ts
 ```
 
-## Loading dependencies on demand
+## Importing dependencies \{#loading-dependencies-on-demand}
 
-Every `rs` command loads and executes the Rstack configuration file, then resolves only the configuration functions needed by that command.
+Rstack keeps a project's build, test, lint, formatting, and other settings in one `rstack.config.*` file. When a command loads the config file, it also loads every top-level import, even if it does not use the related configuration. Importing every tool and plugin at the top level can therefore add startup overhead to commands such as `rs lint` and `rs fmt`.
 
-When a configuration needs to import plugins or other tool-specific dependencies, use an async configuration function and load those dependencies with dynamic `import()` inside it. This ensures that they are loaded only when the configuration is resolved.
+Choose the import style based on the config contents:
+
+- Prefer simpler static imports when the config is only for an application and its tests, a library and its tests, or a documentation site.
+- If the same config also includes lint, formatting, or staged-file checks, consider dynamically importing dependencies inside the relevant async configuration function. This lets checks skip those dependencies.
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';
@@ -59,6 +62,12 @@ define.app(async () => {
     plugins: [pluginReact()],
   };
 });
+
+define.lint(({ js }) => [js.configs.recommended]);
+
+define.fmt({
+  singleQuote: true,
+});
 ```
 
 ## Configuration APIs
diff --git a/website/docs/en/guide/monorepo.mdx b/website/docs/en/guide/monorepo.mdx
index 1e949e2b..c8f80f57 100644
--- a/website/docs/en/guide/monorepo.mdx
+++ b/website/docs/en/guide/monorepo.mdx
@@ -117,13 +117,11 @@ Rstack CLI loads the configuration from the current working directory. It does n
 A web application usually needs application build configuration and optional test configuration:
 
 ```ts title="apps/web/rstack.config.ts"
+import { pluginReact } from '@rsbuild/plugin-react';
 import { define } from 'rstack';
 
-define.app(async () => {
-  const { pluginReact } = await import('@rsbuild/plugin-react');
-  return {
-    plugins: [pluginReact()],
-  };
+define.app({
+  plugins: [pluginReact()],
 });
 
 define.test({
diff --git a/website/docs/zh/guide/configuration.mdx b/website/docs/zh/guide/configuration.mdx
index 06939f84..cd9558e4 100644
--- a/website/docs/zh/guide/configuration.mdx
+++ b/website/docs/zh/guide/configuration.mdx
@@ -44,11 +44,14 @@ Rstack CLI 默认会查找使用以下任一文件名的配置文件：
 rs build --config ./configs/rstack.config.ts
 ```
 
-## 按需加载依赖 \{#loading-dependencies-on-demand}
+## 导入依赖 \{#loading-dependencies-on-demand}
 
-每次执行 `rs` 命令时，Rstack CLI 都会加载并执行配置文件，然后只解析当前命令需要的配置函数。
+Rstack 将项目的构建、测试、代码检查、格式化等配置集中在一个 `rstack.config.*` 文件中。命令加载配置文件时，会同时加载所有顶层 `import`，即使当前命令用不到对应的配置。因此，在顶层导入所有工具和插件可能会增加 `rs lint`、`rs fmt` 等命令的启动开销。
 
-如果配置需要导入插件或其他工具专属依赖，请使用异步配置函数，并在函数内通过动态 `import()` 加载这些依赖。这样只有解析该配置时才会加载相关依赖。
+请根据配置内容选择导入方式：
+
+- 如果配置只用于一个应用及其测试、一个库及其测试或一个文档站点，优先使用更简洁的静态导入。
+- 如果同一配置还包含 lint、格式化或暂存文件检查，可在相应的异步配置函数中动态导入依赖，让检查命令跳过这些依赖。
 
 ```ts title="rstack.config.ts"
 import { define } from 'rstack';
@@ -59,6 +62,12 @@ define.app(async () => {
     plugins: [pluginReact()],
   };
 });
+
+define.lint(({ js }) => [js.configs.recommended]);
+
+define.fmt({
+  singleQuote: true,
+});
 ```
 
 ## 配置 API \{#configuration-apis}
diff --git a/website/docs/zh/guide/monorepo.mdx b/website/docs/zh/guide/monorepo.mdx
index f83c7a6d..b953bbb1 100644
--- a/website/docs/zh/guide/monorepo.mdx
+++ b/website/docs/zh/guide/monorepo.mdx
@@ -117,13 +117,11 @@ Rstack CLI 会加载当前工作目录中的配置，不会将子项目配置与
 Web 应用通常需要应用构建配置和可选的测试配置：
 
 ```ts title="apps/web/rstack.config.ts"
+import { pluginReact } from '@rsbuild/plugin-react';
 import { define } from 'rstack';
 
-define.app(async () => {
-  const { pluginReact } = await import('@rsbuild/plugin-react');
-  return {
-    plugins: [pluginReact()],
-  };
+define.app({
+  plugins: [pluginReact()],
 });
 
 define.test({