@lynx-js/rspeedy 0.13.6 → 0.14.1

package/dist/index.d.ts

@@ -75,20 +75,7 @@ export declare interface BuildCache {
      * An array of files containing build dependencies.
      * Rspack will use the hash of each of these files to invalidate the persistent cache.
      *
-     * @remarks
-     *
-     * Rspeedy will use the following configuration files as the default build dependencies:
-     *
-     * - `package.json`
-     *
-     * - `tsconfig.json` (or `source.tsconfigPath`)
-     *
-     * - `.env`, `.env.*`
-     *
-     * - `tailwindcss.config.*`
-     *
-     * When using Rspeedy CLI, it will also automatically add
-     * `lynx.config.js` to the build dependencies.
+     * @defaultValue `['package.json', 'tsconfig.json' (or source.tsconfigPath), '.env', '.env.*', 'tailwindcss.config.*']`; when using the Rspeedy CLI with `performance.buildCache` enabled, the loaded `lynx.config.*` file is also added.
      *
      * @example
      *
@@ -118,9 +105,11 @@ export declare interface ChunkSplit {
     /**
      * The ChunkSplitting strategy.
      *
+     * @defaultValue In Rsbuild's default chunk splitting behavior, the strategy is `'split-by-experience'`.
+     *
      * @remarks
      *
-     * - `split-by-experience`(default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.
+     * - `split-by-experience`(Rsbuild default): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.
      *
      * - `split-by-module`: split by NPM package granularity, each NPM package corresponds to a chunk.
      *
@@ -168,6 +157,8 @@ export declare interface ChunkSplit {
     /**
      * Custom Rspack chunk splitting config can be specified.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * - Split `@lynx-js/react` and `react-router` into chunk `lib-react`.
@@ -210,7 +201,9 @@ export declare interface ChunkSplitBySize {
      */
     strategy: 'split-by-size';
     /**
-     * The minimum size of a chunk, unit in bytes. Defaults to `10000`.
+     * The minimum size of a chunk, unit in bytes.
+     *
+     * @defaultValue 10000
      *
      * @example
      *
@@ -229,7 +222,9 @@ export declare interface ChunkSplitBySize {
      */
     minSize?: number | undefined;
     /**
-     * The maximum size of a chunk, unit in bytes. Defaults to `Number.POSITIVE_INFINITY`.
+     * The maximum size of a chunk, unit in bytes.
+     *
+     * @defaultValue `Number.POSITIVE_INFINITY`
      *
      * @example
      *
@@ -249,6 +244,8 @@ export declare interface ChunkSplitBySize {
     maxSize?: number | undefined;
     /**
      * {@inheritdoc ChunkSplit.override}
+     *
+     * @defaultValue undefined
      */
     override?: Rspack.Configuration extends {
         optimization?: {
@@ -270,6 +267,8 @@ export declare interface ChunkSplitCustom {
     /**
      * {@inheritdoc ChunkSplit.override}
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * - Split `@lynx-js/react` and `react-router` into chunk `lib-react`.
@@ -309,11 +308,15 @@ export declare interface ChunkSplitCustom {
 export declare 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.
@@ -358,23 +361,7 @@ export declare 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
      *
@@ -415,31 +402,45 @@ export declare interface Config {
     mode?: 'development' | 'production' | 'none' | undefined;
     /**
      * 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;
     /**
      * 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.
      */
@@ -455,6 +456,8 @@ export declare 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'`
@@ -467,6 +470,8 @@ export declare interface ConfigParams {
     /**
      * The CLI command of Rspeedy.
      *
+     * @defaultValue When `loadConfig` evaluates a config function, this value is `process.argv[2] ?? 'build'`
+     *
      * @remarks
      *
      * Possible values:
@@ -585,10 +590,14 @@ export declare interface CreateRspeedyOptions {
 export declare interface CssExtract {
     /**
      * {@inheritdoc @lynx-js/css-extract-webpack-plugin#LoaderOptions}
+     *
+     * @defaultValue undefined
      */
     loaderOptions?: CssExtractRspackLoaderOptions | undefined;
     /**
      * {@inheritdoc @lynx-js/css-extract-webpack-plugin#CssExtractRspackPluginOptions}
+     *
+     * @defaultValue undefined
      */
     pluginOptions?: CssExtractRspackPluginOptions | undefined;
 }
@@ -632,6 +641,8 @@ export declare interface CssExtractRspackLoaderOptions {
      * ```
      *
      * @public
+     *
+     * @defaultValue true
      */
     esModule?: boolean | undefined;
 }
@@ -644,10 +655,14 @@ export declare interface CssExtractRspackLoaderOptions {
 export declare interface CssExtractRspackPluginOptions {
     /**
      * {@inheritdoc @lynx-js/css-extract-webpack-plugin#CssExtractRspackPluginOptions.ignoreOrder}
+     *
+     * @defaultValue undefined
      */
     ignoreOrder?: boolean | undefined;
     /**
      * {@inheritdoc @lynx-js/css-extract-webpack-plugin#CssExtractRspackPluginOptions.pathinfo}
+     *
+     * @defaultValue undefined
      */
     pathinfo?: boolean | undefined;
 }
@@ -661,13 +676,9 @@ export declare interface CssLoader {
     /**
      * The option `importLoaders` allows you to configure how many loaders before `css-loader` should be applied to `@imported` resources and CSS modules imports.
      *
-     * @remarks
-     *
-     * The default value of `importLoaders` is:
+     * @defaultValue `1` when compiling CSS files and `2` when compiling Sass or Less files
      *
-     * - `1` when compiling CSS files
-     *
-     * - `2` when compiling Sass or Less files
+     * @remarks
      *
      * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#importloaders | css-loader#import-loaders} for details.
      */
@@ -675,6 +686,8 @@ export declare interface CssLoader {
     /**
      * The {@link CssLoaderModules | cssLoader.modules} option enables/disables the CSS Modules specification and setup basic behavior.
      *
+     * @defaultValue Enables CSS Modules with automatic `*.module.*` detection, camelCase exports, `namedExport: false`, and `localIdentName` inherited from `output.cssModules.localIdentName`.
+     *
      * @example
      *
      * Using `false` value to increase performance because we avoid parsing CSS Modules features, it will be useful for developers who use vanilla css or use other technologies.
@@ -736,19 +749,27 @@ export declare interface CssLoader {
 export declare interface CssLoaderModules {
     /**
      * {@inheritdoc CssModules.auto}
+     *
+     * @defaultValue true
      */
     auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
     /**
      * {@inheritdoc CssModules.exportLocalsConvention}
+     *
+     * @defaultValue `'camelCase'`
      */
     exportLocalsConvention?: CssModuleLocalsConvention | undefined;
     /**
      * {@inheritdoc CssModules.localIdentName}
+     *
+     * @defaultValue `'[local]-[hash:base64:6]'`
      */
     localIdentName?: string | undefined;
     /**
      * Enables/disables ES modules named export for locals.
      *
+     * @defaultValue false
+     *
      * @example
      *
      * - `style.css`
@@ -799,6 +820,8 @@ export declare 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:
@@ -834,6 +857,8 @@ export declare 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.
@@ -842,6 +867,8 @@ export declare interface CssModules {
     /**
      * The style of exported class names.
      *
+     * @defaultValue `'camelCase'`
+     *
      * @remarks
      *
      * Given the various `exportLocalsConvention` values, the behavior is described as follows:
@@ -862,9 +889,9 @@ export declare 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:
      *
@@ -922,6 +949,8 @@ export declare interface Decorators {
     /**
      * Specify the decorator syntax version to be used.
      *
+     * @defaultValue `'2022-03'`
+     *
      * @remarks
      *
      * If you want to know the differences between different decorators versions, you can refer to: {@link https://github.com/tc39/proposal-decorators?tab=readme-ov-file#how-does-this-proposal-compare-to-other-versions-of-decorators | How does this proposal compare to other versions of decorators?}
@@ -1091,8 +1120,13 @@ export declare function defineConfig(config: (params: ConfigParams) => Promise<C
 export declare 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:
      *
@@ -1150,14 +1184,16 @@ export declare interface Dev {
     assetPrefix?: string | boolean | undefined;
     /**
      * Configuration of the development client.
+     *
+     * @defaultValue undefined
      */
     client?: DevClient | 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}.
      *
@@ -1196,7 +1232,7 @@ export declare 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.
      *
@@ -1235,6 +1271,8 @@ export declare 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.
@@ -1272,6 +1310,8 @@ export declare 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`}.
@@ -1297,7 +1337,7 @@ export declare interface Dev {
     /**
      * Whether to display progress bar during compilation.
      *
-     * Defaults to `true`.
+     * @defaultValue true
      *
      * @example
      *
@@ -1345,9 +1385,7 @@ export declare interface DevClient {
     /**
      * The path to websocket.
      *
-     * @remarks
-     *
-     * Defaults to `require.resolve('@lynx-js/websocket')`
+     * @defaultValue `require.resolve('@lynx-js/websocket')`
      */
     websocketTransport?: string | undefined;
 }
@@ -1365,11 +1403,7 @@ export declare 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;
 }
@@ -1453,16 +1487,14 @@ export declare interface EntryDescription {
     /**
      * The path to the entry module(s).
      *
-     * @remarks
-     *
-     * If no value is provided, the default value `src/index.js` will be used.
-     *
      * @defaultValue `'./src/index.js'`
      */
     import?: string | string[] | undefined;
     /**
      * This is an important option when using on-demand-loading or loading external resources like images, files, etc. If an incorrect value is specified you'll receive 404 errors while loading these resources.
      *
+     * @defaultValue undefined
+     *
      * @see https://webpack.js.org/configuration/output/#outputpublicpath
      */
     publicPath?: string | undefined;
@@ -1522,11 +1554,9 @@ export declare interface Filename {
     /**
      * The name of the bundle files.
      *
-     * @remarks
-     *
-     * Default values:
+     * @defaultValue `'[name].[platform].bundle'`
      *
-     * - `'[name].[platform].bundle'`
+     * @remarks
      *
      * The following placeholder is supported:
      *
@@ -1574,11 +1604,9 @@ export declare interface Filename {
      *
      * Use {@link Filename.bundle} instead.
      *
-     * @remarks
-     *
-     * Default values:
+     * @defaultValue `'[name].[platform].bundle'`
      *
-     * - `'[name].lynx.bundle'`
+     * @remarks
      *
      * The following placeholder is supported:
      *
@@ -1621,12 +1649,7 @@ export declare interface Filename {
     /**
      * The name of the JavaScript files.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - Development: `'[name].js'`
-     * - Production: `'[name].[contenthash:8].js'`
+     * @defaultValue `'[name].js'` in development, `'[name].[contenthash:8].js'` in production web builds, and `'[name].js'` in production node builds
      *
      * @example
      *
@@ -1655,11 +1678,7 @@ export declare interface Filename {
     /**
      * The name of the CSS files.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].css'`
+     * @defaultValue `'[name]/[name].css'`
      *
      * @example
      *
@@ -1688,61 +1707,37 @@ export declare interface Filename {
     /**
      * The name of the SVG images.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].[contenthash:8].svg'`
+     * @defaultValue `'[name].[contenthash:8].svg'`
      */
     svg?: Rspack.AssetModuleFilename | undefined;
     /**
      * The name of the font files.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].[contenthash:8][ext]'`
+     * @defaultValue `'[name].[contenthash:8][ext]'`
      */
     font?: Rspack.AssetModuleFilename | undefined;
     /**
      * The name of non-SVG images.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].[contenthash:8][ext]'`
+     * @defaultValue `'[name].[contenthash:8][ext]'`
      */
     image?: Rspack.AssetModuleFilename | undefined;
     /**
      * The name of media assets, such as video.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].[contenthash:8][ext]'`
+     * @defaultValue `'[name].[contenthash:8][ext]'`
      */
     media?: Rspack.AssetModuleFilename | undefined;
     /**
      * The name of WebAssembly files.
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[hash].module.wasm'`
+     * @defaultValue `'[contenthash:8].module.wasm'`
      */
     wasm?: Rspack.WebassemblyModuleFilename;
     /**
      * The name of other assets, except for above (image, svg, font, html, wasm...)
      *
-     * @remarks
-     *
-     * Default values:
-     *
-     * - `'[name].[contenthash:8][ext]'`
+     * @defaultValue `'[name].[contenthash:8][ext]'`
      */
     assets?: Rspack.AssetModuleFilename;
 }
@@ -1774,7 +1769,17 @@ export declare function loadConfig(loadConfigOptions: LoadConfigOptions): Promis
  * @public
  */
 export declare 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;
 }
 
@@ -1845,6 +1850,8 @@ export declare interface Minify {
     /**
      * Whether enable the CSS minification.
      *
+     * @defaultValue When `output.minify` is enabled and `css` is unset, this defaults to `true`.
+     *
      * @remarks
      *
      * When building for production, {@link https://github.com/rspack-contrib/rsbuild-plugin-css-minimizer | @rsbuild/plugin-css-minimizer} is used to minify CSS assets for better transmission efficiency.
@@ -1869,6 +1876,8 @@ export declare interface Minify {
     /**
      * Whether enable the JavaScript minification.
      *
+     * @defaultValue When `output.minify` is enabled and `js` is unset, this defaults to `true`.
+     *
      * @example
      *
      * - Disable the JavaScript minification.
@@ -1889,6 +1898,8 @@ export declare interface Minify {
     /**
      * {@link Minify.jsOptions} is used to configure SWC minification options.
      *
+     * @defaultValue When JavaScript minification is enabled and `jsOptions` is unset, this defaults to `{}`.
+     *
      * @remarks
      *
      * For detailed configurations, please refer to {@link https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin | SwcJsMinimizerRspackPlugin}.
@@ -1914,6 +1925,59 @@ export declare interface Minify {
      * ```
      */
     jsOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
+    /**
+     * {@link Minify.mainThreadOptions} is used to override
+     * {@link Minify.jsOptions} for main-thread bundles.
+     *
+     * @defaultValue undefined
+     *
+     * @remarks
+     *
+     * This option is deep-merged into {@link Minify.jsOptions}.
+     * It is mainly used together with ReactLynx dual-thread outputs so that
+     * main-thread and background-thread bundles can use different compress rules.
+     *
+     * @example
+     *
+     * ```ts
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   output: {
+     *     minify: {
+     *       jsOptions: {
+     *         minimizerOptions: {
+     *           compress: {
+     *             pure_funcs: ['console.log'],
+     *           },
+     *         },
+     *       },
+     *       mainThreadOptions: {
+     *         minimizerOptions: {
+     *           compress: {
+     *             pure_funcs: ['NativeModules.call', 'lynx.getJSModule'],
+     *           },
+     *         },
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    mainThreadOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
+    /**
+     * {@link Minify.backgroundOptions} is used to override
+     * {@link Minify.jsOptions} for background-thread bundles.
+     *
+     * @defaultValue undefined
+     *
+     * @remarks
+     *
+     * This option is deep-merged into {@link Minify.jsOptions}.
+     * It is mainly used together with ReactLynx dual-thread outputs so that
+     * main-thread and background-thread bundles can use different compress rules.
+     */
+    backgroundOptions?: Rspack.SwcJsMinimizerRspackPluginOptions | undefined;
 }
 
 /**
@@ -1924,6 +1988,8 @@ export declare interface Output {
     /**
      * The {@link Output.assetPrefix} is used to set the URL prefix for static assets.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * The functionality of {@link Output.assetPrefix} is basically the same as the {@link https://www.rspack.dev/config/output#outputpublicpath | output.publicPath}
@@ -1950,11 +2016,7 @@ export declare interface Output {
     /**
      * The {@link Output.cleanDistPath} option determines whether all files in the output directory (default: `dist`) are removed before the build starts.
      *
-     * @remarks
-     *
-     * By default, if the output directory is a subdirectory of the project root path, Rspeedy will automatically clean all files in the build directory.
-     *
-     * When {@link https://rsbuild.dev/config/output/dist-path#root-directory | output.distPath.root} is an external directory or the same as the project root directory, `cleanDistPath` is not enabled by default to prevent accidental deletion of files from other directories.
+     * @defaultValue Automatically enabled when `output.distPath.root` is a subdirectory of the project root; otherwise disabled.
      *
      * @example
      *
@@ -1985,6 +2047,8 @@ export declare interface Output {
     /**
      * The {@link Output.copy} option is used for copying files to the dist directory.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * For more options, see {@link https://rspack.dev/plugins/rspack/copy-rspack-plugin | Rspack.CopyRspackPlugin}.
@@ -2027,6 +2091,8 @@ export declare interface Output {
     /**
      * The {@link CssModules} option is used for the customization of CSS Modules configurations.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * The CSS module is enabled for `*.module.css`, `*.module.scss` and `*.module.less`.
@@ -2066,9 +2132,7 @@ export declare interface Output {
     /**
      * The {@link Output.dataUriLimit} option is used to set the size threshold to inline static assets such as images and fonts.
      *
-     * @remarks
-     *
-     * The default value of `dataUriLimit` is 2kB.
+     * @defaultValue 2048
      *
      * @example
      *
@@ -2129,6 +2193,8 @@ export declare interface Output {
     /**
      * Set the directory of the dist files.
      *
+     * @defaultValue Uses Rsbuild's default distPath configuration with `root: 'dist'`.
+     *
      * @remarks
      *
      * More options can be found at {@link https://rsbuild.dev/config/output/dist-path | Rsbuild - distPath}.
@@ -2152,6 +2218,8 @@ export declare interface Output {
     /**
      * The {@link Filename} determines the name of the JavaScript bundle file to be output. These bundles will be written to the directory specified by output.path.
      *
+     * @defaultValue `{ bundle: '[name].[platform].bundle', template: '[name].[platform].bundle' }`
+     *
      * @remarks
      *
      * If a string is provided, it will be used as {@link Filename.bundle}.
@@ -2171,6 +2239,8 @@ export declare interface Output {
     /**
      * The {@link Output.filenameHash} option controls whether to add a hash value to the filename after the production build.
      *
+     * @defaultValue In production web builds, Rsbuild defaults this option to `true`; development builds and non-web outputs omit hashes by default.
+     *
      * @remarks
      *
      * {@link Output.filename} has a higher priority than {@link Output.filenameHash}.
@@ -2215,9 +2285,9 @@ export declare interface Output {
     /**
      * The {@link Output.inlineScripts} option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`).
      *
-     * @remarks
+     * @defaultValue Rspeedy defaults this to `true` and only switches it to `false` when the user explicitly sets `performance.chunkSplit.strategy` to a value other than `'all-in-one'`.
      *
-     * If no value is provided, the default value would be `true`, which means all background thread scripts will be inlined.
+     * @remarks
      *
      * This is different with {@link https://rsbuild.dev/config/output/inline-scripts | output.inlineScripts } since we normally want to inline scripts in Lynx bundle (`.lynx.bundle`).
      *
@@ -2244,9 +2314,9 @@ export declare interface Output {
     /**
      * The {@link Output.legalComments} controls how to handle the legal comment.
      *
-     * @remarks
+     * @defaultValue `'none'`
      *
-     * If no value is provided, the default value would be `'none'`.
+     * @remarks
      *
      * This is different with Rsbuild since we normally do not want a `.LEGAL.txt` file in Lynx outputs.
      *
@@ -2262,6 +2332,8 @@ export declare interface Output {
     /**
      * The {@link Minify} configures whether to enable code minification in the production build, or to configure minimizer options.
      *
+     * @defaultValue `true` in production builds and `false` otherwise
+     *
      * @example
      *
      * Disable minification.
@@ -2277,6 +2349,8 @@ export declare interface Output {
     minify?: Minify | boolean | undefined;
     /**
      * The {@link SourceMap} configures whether and how to generate source-map for outputs.
+     *
+     * @defaultValue When this option is unset, JavaScript source maps use `'cheap-module-source-map'` in development and are otherwise disabled; CSS source maps are disabled.
      */
     sourceMap?: boolean | SourceMap | undefined;
 }
@@ -2290,6 +2364,8 @@ export declare interface Performance {
     /**
      * Enable or configure persistent build cache.
      *
+     * @defaultValue false
+     *
      * @beta This feature is experimental and may be changed in the future.
      *
      * @example
@@ -2326,14 +2402,14 @@ export declare interface Performance {
     buildCache?: BuildCache | boolean | undefined;
     /**
      * {@link Performance.chunkSplit} is used to configure the chunk splitting strategy.
+     *
+     * @defaultValue For web builds, Rsbuild currently uses `{ strategy: 'split-by-experience' }` when this option is unset.
      */
     chunkSplit?: ChunkSplit | ChunkSplitBySize | ChunkSplitCustom | undefined;
     /**
      * Whether capture timing information in the build time and the runtime, the same as the {@link https://rspack.dev/config/other-options#profile | profile} config of Rspack.
      *
-     * @remarks
-     *
-     * This option would be `true` when `DEBUG` environment variable contains `rspeedy`.
+     * @defaultValue Rspeedy sets this to `true` when `DEBUG` contains `rspeedy`; otherwise it leaves the option unset.
      *
      * @example
      *
@@ -2357,6 +2433,8 @@ export declare interface Performance {
     /**
      * Whether to remove `console.[methodName]` in production build.
      *
+     * @defaultValue false
+     *
      * @example
      *
      * - Remove all `console` methods
@@ -2389,6 +2467,8 @@ export declare interface Performance {
     /**
      * Whether to print the file sizes after production build.
      *
+     * @defaultValue true
+     *
      * {@link Performance.printFileSize}
      *
      * See {@link https://rsbuild.dev/config/performance/print-file-size | Rsbuild - performance.printFileSize} for details.
@@ -2511,6 +2591,8 @@ export declare interface Resolve {
     /**
      * Create aliases to `import` or `require` certain modules more easily.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * A trailing `$` can also be added to the given object's keys to signify an exact match:
@@ -2591,6 +2673,9 @@ export declare interface Resolve {
     /**
      * Set the strategy for path alias resolution, to control the priority relationship
      * between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild.
+     *
+     * @defaultValue `'prefer-tsconfig'`
+     *
      * - `prefer-tsconfig` (default): The `paths` option in `tsconfig.json` will take precedence over the
      * `resolve.alias` option of Rsbuild.
      * - `prefer-alias`: The `resolve.alias` option of Rsbuild will take precedence over the
@@ -2615,6 +2700,8 @@ export declare interface Resolve {
     /**
      * Force to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * {@link Resolve.dedupe} is implemented based on {@link Resolve.alias}, it will get the path of the specified package through `require.resolve` in the project root directory and set it to the alias.
@@ -2639,7 +2726,7 @@ export declare interface Resolve {
     /**
      * Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.
      *
-     * Default: `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json', '.cjs']`
+     * @defaultValue `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json', '.cjs']`
      *
      * For example, if importing './index', Rsbuild will try to resolve using the following order:
      *
@@ -2707,8 +2794,10 @@ export declare interface Server {
     /**
      * Configure the base path of the server.
      *
+     * @defaultValue `'/'`
+     *
      * @remarks
-     * By default, the base path of the server is `/`, and users can access lynx bundle through `http://<host>:<port>/main.lynx.bundle`
+     * Users can access lynx bundle through `http://<host>:<port>/main.lynx.bundle` by default.
      *
      * If you want to access lynx bundle through `http://<host>:<port>/foo/main.lynx.bundle`, you can change `server.base` to `/foo`
      *
@@ -2729,7 +2818,7 @@ export declare interface Server {
     /**
      * Configure whether to enable {@link https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression | gzip compression } for static assets served by the dev server or preview server.
      *
-     * Default: true
+     * @defaultValue true
      *
      * See {@link https://rsbuild.rs/config/server/compress | Rsbuild - server.compress } for details.
      *
@@ -2782,6 +2871,8 @@ export declare interface Server {
     /**
      * Configure CORS for the dev server or preview server.
      *
+     * @defaultValue Uses Rsbuild's default CORS options.
+     *
      * - Set to an object to enable CORS with the specified options.
      *
      * - Set to `true` to enable CORS with the default options (allows all origins, not recommended).
@@ -2806,6 +2897,8 @@ export declare interface Server {
     /**
      * Adds headers to all responses.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * ```js
@@ -2823,8 +2916,10 @@ export declare interface Server {
     /**
      * Specify the host that the Rspeedy Server listens to.
      *
+     * @defaultValue undefined
+     *
      * @remarks
-     * By default, the server listens on local network IP, for example, `192.168.1.50`, verify your local net IP by the command `ifconfig` on your system for (en0 for MacOS and eth0 for LinuxOS users). In case you have multiple local network IP(s) particularly when you are running dockers on the host machine, then you can specify your desired host IP.
+     * During `rspeedy dev`, if `server.host` is unset, the dev plugin resolves dev-server-related URLs and client host settings with a detected local IPv4 address, such as `192.168.1.50`. If you have multiple network interfaces, set `server.host` explicitly to choose the desired address.
      *
      * @example
      *
@@ -2843,8 +2938,10 @@ export declare interface Server {
     /**
      * Specify the port that the Rspeedy Server listens to.
      *
+     * @defaultValue Rsbuild defaults this option to `3000`.
+     *
      * @remarks
-     * By default, the server listens on port `3000` and automatically increments the port number when the port is occupied.
+     * By default, the server automatically increments the port number when the configured port is occupied.
      *
      * @example
      *
@@ -2863,6 +2960,8 @@ export declare interface Server {
     /**
      * Configure proxy rules for the dev server or preview server to proxy requests to the specified service.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * ```js
@@ -2881,7 +2980,9 @@ export declare interface Server {
     /**
      * When a port is occupied, Rspeedy will automatically increment the port number until an available port is found.
      *
-     * Set strictPort to true and Rspeedy will throw an exception when the port is occupied.
+     * @defaultValue false
+     *
+     * By default, strict port mode is disabled. Set strictPort to true and Rspeedy will throw an exception when the port is occupied.
      */
     strictPort?: boolean | undefined;
 }
@@ -2896,10 +2997,14 @@ export declare interface Source {
      * {@inheritdoc Resolve.alias}
      *
      * @deprecated - Use {@link Resolve.alias} instead.
+     *
+     * @defaultValue undefined
      */
     alias?: Record<string, string | false | string[]> | undefined;
     /**
-     * Include additional files that should be treated as static assets. Defaults to be `undefined`.
+     * Include additional files that should be treated as static assets.
+     *
+     * @defaultValue undefined
      *
      * @remarks
      *
@@ -2926,6 +3031,8 @@ export declare interface Source {
     /**
      * Used to configure the decorators syntax.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * See {@link Decorators.version} for more information.
@@ -2934,6 +3041,8 @@ export declare interface Source {
     /**
      * The `define` options is used to define some values or expressions at compile time.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * Using `define` for environment variables.
@@ -3026,10 +3135,6 @@ export declare interface Source {
     /**
      * The {@link Entry} option is used to set the entry module.
      *
-     * @remarks
-     *
-     * If no value is provided, the default value `'./src/index.js'` will be used.
-     *
      * @defaultValue `'./src/index.js'`
      *
      * @example
@@ -3096,6 +3201,8 @@ export declare interface Source {
     /**
      * The `source.exclude` is used to specify JavaScript files that should be excluded from compilation.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * By default, Rsbuild compiles JavaScript files in the current directory and TypeScript/JSX files
@@ -3157,6 +3264,8 @@ export declare interface Source {
     /**
      * The `source.include` is used to specify additional JavaScript files that need to be compiled.
      *
+     * @defaultValue When unset, Rsbuild compiles JavaScript files in the current directory and TypeScript or JSX files in all directories, while excluding JavaScript files under `node_modules`.
+     *
      * @remarks
      *
      * To avoid redundant compilation, by default, Rsbuild only compiles JavaScript
@@ -3233,6 +3342,8 @@ export declare interface Source {
      * Add a script before the entry file of each page. This script will be executed before the page code.
      * It can be used to execute global logics, such as injecting polyfills, setting global styles, etc.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * See {@link https://rsbuild.dev/config/source/pre-entry | source.preEntry} for more details.
@@ -3254,6 +3365,8 @@ export declare interface Source {
     /**
      * The {@link TransformImport} option transforms the import paths to enable modular imports from subpaths of third-party packages, similar to the functionality provided by {@link https://npmjs.com/package/babel-plugin-import | babel-plugin-import}.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * When using the TUX component library, you can import components on demand with the following config:
@@ -3287,7 +3400,9 @@ export declare interface Source {
      */
     transformImport?: TransformImport[] | undefined;
     /**
-     * Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path. Defaults to be `./tsconfig.json`.
+     * Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path.
+     *
+     * @defaultValue `'./tsconfig.json'`
      *
      * @remarks
      *
@@ -3322,9 +3437,9 @@ export declare interface SourceMap {
     /**
      * How the source map should be generated. Setting it to `false` will disable the source map.
      *
-     * @remarks
+     * @defaultValue When `output.sourceMap` is an object and `js` is unset, it defaults to `'cheap-module-source-map'` in development and `false` in production.
      *
-     * Defaults to `'cheap-module-source-map'` at development, `false` at production.
+     * @remarks
      *
      * See {@link https://rspack.dev/config/devtool | Rspack - Devtool} for details.
      *
@@ -3390,6 +3505,8 @@ export declare interface Tools {
     /**
      * The {@link Tools.bundlerChain} changes the options of {@link https://www.rspack.dev | Rspack} using {@link https://github.com/rspack-contrib/rspack-chain | rspack-chain}.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * ```js
@@ -3410,6 +3527,8 @@ export declare interface Tools {
     /**
      * The {@link CssLoader} controls the options of {@link https://github.com/webpack-contrib/css-loader | css-loader}.
      *
+     * @defaultValue Uses defaults derived from `output.cssModules` and `output.sourceMap`, with `importLoaders` set to `1` for CSS files and `2` for Sass/Less files.
+     *
      * @remarks
      *
      * The default option is as follow:
@@ -3431,11 +3550,18 @@ export declare interface Tools {
     cssLoader?: CssLoader | undefined;
     /**
      * The {@link CssExtract} controls the options of {@link https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin | CssExtractRspackPlugin}
+     *
+     * @defaultValue undefined
      */
     cssExtract?: CssExtract | undefined;
     /**
      * The {@link Tools.rsdoctor} controls the options of {@link https://rsdoctor.dev/ | Rsdoctor}.
      *
+     * @defaultValue undefined
+     *
+     * @remarks
+     * Setting `RSDOCTOR=true` enables Rsdoctor. When it is enabled, Rspeedy merges additional plugin defaults during config normalization.
+     *
      * @example
      *
      * - Use the built-in Rsdoctor.
@@ -3458,6 +3584,8 @@ export declare interface Tools {
     /**
      * The {@link Tools.rspack} controls the options of {@link https://www.rspack.dev/ | Rspack}.
      *
+     * @defaultValue undefined
+     *
      * @example
      *
      * - Use object config
@@ -3543,6 +3671,8 @@ export declare interface Tools {
     rspack?: ToolsConfig['rspack'] | undefined;
     /**
      * The {@link Tools.swc} controls the options of {@link https://rspack.dev/guide/features/builtin-swc-loader | builtin:swc-loader}.
+     *
+     * @defaultValue undefined
      */
     swc?: ToolsConfig['swc'] | undefined;
 }
@@ -3556,6 +3686,8 @@ export declare interface TransformImport {
     /**
      * Whether to convert camelCase imports to kebab-case.
      *
+     * @defaultValue Rsbuild defaults this option to `true`.
+     *
      * @example
      *
      * - Input:
@@ -3571,7 +3703,7 @@ export declare interface TransformImport {
      * import ButtonGroup from 'foo/button-group'
      * ```
      *
-     * When set to `false` or `undefined`:
+     * When set to `false`:
      * ```js
      * import ButtonGroup from 'foo/ButtonGroup'
      * ```
@@ -3580,6 +3712,8 @@ export declare interface TransformImport {
     /**
      * Customize the transformed path.
      *
+     * @defaultValue undefined
+     *
      * @remarks
      *
      * You you can specify the format of the transformed path.
@@ -3609,9 +3743,7 @@ export declare interface TransformImport {
     /**
      * Used to splice the transformed path, the splicing rule is `${libraryName}/${libraryDirectory}/${member}`, where member is the imported member.
      *
-     * @remarks
-     *
-     * The default value is `'lib'`.
+     * @defaultValue `'lib'`
      *
      * @example
      *
@@ -3631,6 +3763,8 @@ export declare interface TransformImport {
     /**
      * Whether to convert import statements to default imports.
      *
+     * @defaultValue Rsbuild defaults this option to `true`.
+     *
      * @example
      *
      * - Input:
@@ -3646,7 +3780,7 @@ export declare interface TransformImport {
      * import Button from 'foo/button'
      * ```
      *
-     * When set to `false` or `undefined`:
+     * When set to `false`:
      * ```js
      * import { Button } from 'foo/button'
      * ```