docs(rspeedy): document config default values

.changeset/crazy-women-raise.md

@@ -0,0 +1,3 @@
+---
+
+---

.github/rspeedy-config-docs.instructions.md

@@ -0,0 +1,5 @@
+---
+applyTo: "packages/rspeedy/core/src/config/**/*.ts"
+---
+
+When documenting config types in `packages/rspeedy/core/src/config`, record the user-facing default value of the option in `@defaultValue` instead of describing it in `@remarks`. Verify each documented default against the local implementation or the referenced upstream Rsbuild behavior before writing it down. If an existing `@remarks` section explains the default behavior, move that information into `@defaultValue` and keep `@remarks` for non-default semantics, conditional runtime normalization, or tool-injected behavior that is not the option's direct default.

packages/rspeedy/core/etc/rspeedy.api.md

@@ -220,9 +220,7 @@ export function loadConfig(loadConfigOptions: LoadConfigOptions): Promise<LoadCo
 
 // @public
 export interface LoadConfigOptions {
-    // (undocumented)
     configPath?: string | undefined;
-    // (undocumented)
     cwd?: string | undefined;
 }
 

packages/rspeedy/core/src/config/defineConfig.ts

@@ -13,6 +13,8 @@ export interface ConfigParams {
   /**
    * The value of `process.env['NODE_ENV']`
    *
+   * @defaultValue When `loadConfig` evaluates a config function, this value is `process.env.NODE_ENV ?? 'production'`
+   *
    * @remarks
    * Common values include (non-exhaustive):
    * - `'production'`
@@ -25,6 +27,8 @@ export interface ConfigParams {
   /**
    * The CLI command of Rspeedy.
    *
+   * @defaultValue When `loadConfig` evaluates a config function, this value is `process.argv[2] ?? 'build'`
+   *
    * @remarks
    *
    * Possible values:

packages/rspeedy/core/src/config/dev/client.ts

@@ -11,9 +11,7 @@ export interface Client {
   /**
    * The path to websocket.
    *
-   * @remarks
-   *
-   * Defaults to `require.resolve('@lynx-js/websocket')`
+   * @defaultValue `require.resolve('@lynx-js/websocket')`
    */
   websocketTransport?: string | undefined
 }

packages/rspeedy/core/src/config/dev/index.ts

@@ -12,8 +12,13 @@ import type { Client } from './client.js'
 export interface Dev {
   /**
    * The {@link Dev.assetPrefix} is used to set the URL prefix for static assets during development.
+   *
+   * @defaultValue undefined
+   *
    * @remarks
    *
+   * During `rspeedy dev`, if this option is not set to `false`, the dev plugin normalizes it to `http://<detected-host>:<port>/` and appends `server.base` when configured.
+   *
    * The functionality of {@link Dev.assetPrefix} is basically the same as the {@link https://www.rspack.dev/config/output#outputpublicpath | output.publicPath}
    * config in Rspack. With the following differences:
    *
@@ -72,15 +77,17 @@ export interface Dev {
 
   /**
    * Configuration of the development client.
+   *
+   * @defaultValue undefined
    */
   client?: Client | undefined
 
   /**
    * Whether to enable Hot Module Replacement (HMR).
    *
-   * @remarks
+   * @defaultValue true
    *
-   * Defaults to `true`.
+   * @remarks
    *
    * By default, Rspeedy uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to {@link Dev.liveReload}.
    *
@@ -120,7 +127,7 @@ export interface Dev {
   /**
    * Whether to enable live reload functionality.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    *
    * Live reload is used as a fallback when {@link Dev.hmr} is disabled or cannot be used in certain scenarios. When enabled, the page will automatically refresh when source files are changed.
    *
@@ -160,6 +167,8 @@ export interface Dev {
   /**
    * Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
    *
+   * @defaultValue undefined
+   *
    * @example
    *
    * - Specify the files and directories watched for changes.
@@ -198,6 +207,8 @@ export interface Dev {
   /**
    * Used to control whether the build artifacts of the development environment are written to the disk.
    *
+   * @defaultValue true
+   *
    * @remarks
    *
    * This is bypassed to {@link https://github.com/webpack/webpack-dev-middleware?tab=readme-ov-file#writetodisk | `webpack-dev-middleware`}.
@@ -224,7 +235,7 @@ export interface Dev {
   /**
    * Whether to display progress bar during compilation.
    *
-   * Defaults to `true`.
+   * @defaultValue true
    *
    * @example
    *

packages/rspeedy/core/src/config/index.ts

@@ -20,12 +20,16 @@ import type { Tools } from './tools/index.js'
 export interface Config {
   /**
    * The {@link Dev} option is used to control the behavior related with development. Including: HMR, DevServer, etc.
+   *
+   * @defaultValue undefined
    */
   dev?: Dev | undefined
 
   /**
    * The {@link Config.environments} option is used to set the output environment.
    *
+   * @defaultValue When this option is unset, Rspeedy passes `{ lynx: {} }` to Rsbuild.
+   *
    * @remarks
    *
    * Normally you don't need this if you are not using Lynx for Web.
@@ -71,23 +75,7 @@ export interface Config {
   /**
    * Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.
    *
-   * @remarks
-   *
-   * The default value of mode depends on the `process.env.NODE_ENV` environment variable:
-   *
-   * - If `NODE_ENV` is production, the default value is production.
-   *
-   * - If `NODE_ENV` is development, the default value is development.
-   *
-   * - If `NODE_ENV` has any other value, the default value is none.
-   *
-   * - If you set the value of mode, the value of `NODE_ENV` will be ignored.
-   *
-   * When using Rspeedy's CLI:
-   *
-   * - `rspeedy dev` and `rspeedy preview` will set the default values of `NODE_ENV` and `mode` to `'development'`.
-   *
-   * - `rspeedy build` will set the default values of `NODE_ENV` and `mode` to `'production'`.
+   * @defaultValue Depends on `process.env.NODE_ENV`: `'production'` when `NODE_ENV` is `'production'`, `'development'` when `NODE_ENV` is `'development'`, and `'none'` otherwise. When using Rspeedy's CLI, `rspeedy dev` and `rspeedy preview` default to `'development'`, while `rspeedy build` defaults to `'production'`.
    *
    * @example
    *
@@ -129,31 +117,43 @@ export interface Config {
 
   /**
    * The {@link Output} option is used to set how and where should the bundles and assets output.
+   *
+   * @defaultValue undefined
    */
   output?: Output | undefined
 
   /**
    * The {@link Performance} option is used to optimize the build-time and runtime performance.
+   *
+   * @defaultValue undefined
    */
   performance?: Performance | undefined
 
   /**
    * The {@link Resolve} option is used to control the resolution behavior of Rspack.
+   *
+   * @defaultValue undefined
    */
   resolve?: Resolve | undefined
 
   /**
    * The {@link Server} option changes the behavior of dev-server.
+   *
+   * @defaultValue undefined
    */
   server?: Server | undefined
 
   /**
    * The {@link Source} option changes the behavior of source files.
+   *
+   * @defaultValue undefined
    */
   source?: Source | undefined
 
   /**
    * The {@link Tools} options changes the behavior of various building tools.
+   *
+   * @defaultValue undefined
    */
   tools?: Tools | undefined
 
@@ -162,6 +162,8 @@ export interface Config {
   /**
    * The `plugins` option is used to customize the build process in a variety of ways.
    *
+   * @defaultValue undefined
+   *
    * @remarks
    * Rspeedy use the plugin APIs from {@link https://rsbuild.dev/plugins/dev/index | Rsbuild}. See the corresponding document for developing a plugin.
    */

packages/rspeedy/core/src/config/loadConfig.ts

@@ -62,7 +62,18 @@ export const resolveConfigPath = (
  * @public
  */
 export interface LoadConfigOptions {
+  /**
+   * The config file path to load.
+   *
+   * @defaultValue Automatically resolves `lynx.config.ts`, `lynx.config.js`, `lynx.config.mts`, or `lynx.config.mjs` from `cwd`
+   */
   configPath?: string | undefined
+
+  /**
+   * The working directory used to resolve the config path.
+   *
+   * @defaultValue `process.cwd()`
+   */
   cwd?: string | undefined
 }
 

packages/rspeedy/core/src/config/output/css-modules.ts

@@ -11,6 +11,8 @@ export interface CssModules {
   /**
    * The `auto` option allows CSS modules to be automatically enabled based on their filenames.
    *
+   * @defaultValue true
+   *
    * @remarks
    *
    * Given the various `auto` values, the behavior is described as follows:
@@ -47,6 +49,8 @@ export interface CssModules {
   /**
    * Allows exporting names from global class names, so you can use them via import.
    *
+   * @defaultValue false
+   *
    * @remarks
    *
    * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportglobals | css-loader#exportGlobals} for details.
@@ -56,6 +60,8 @@ export interface CssModules {
   /**
    * The style of exported class names.
    *
+   * @defaultValue `'camelCase'`
+   *
    * @remarks
    *
    * Given the various `exportLocalsConvention` values, the behavior is described as follows:
@@ -77,9 +83,9 @@ export interface CssModules {
   /**
    * Sets the format of the className generated by CSS Modules after compilation.
    *
-   * @remarks
+   * @defaultValue `'[local]-[hash:base64:6]'`
    *
-   * The default value is `'[local]-[hash:base64:6]'` which combines the original class name with a 6-character hash.
+   * @remarks
    *
    * Available placeholders:
    *

packages/rspeedy/core/src/config/output/dist-path.ts

@@ -17,11 +17,7 @@ export interface DistPath extends DistPathConfig {
    *
    * This option is never read and will be removed in the future version.
    *
-   * @remarks
-   *
-   * Default value:
-   *
-   * - `'.rspeedy'`
+   * @defaultValue `'.rspeedy'`
    */
   intermediate?: string | undefined
 }