From 0a52501be1ebef5bbfff2557939a1ed46ac1dbc8 Mon Sep 17 00:00:00 2001 From: Qingyu Wang <40660121+colinaaa@users.noreply.github.com> Date: Sat, 11 Apr 2026 15:57:17 +0800 Subject: [PATCH 1/4] docs(rspeedy): document config default values --- .github/rspeedy-config-docs.instructions.md | 5 ++ packages/rspeedy/core/etc/rspeedy.api.md | 2 - .../rspeedy/core/src/config/defineConfig.ts | 4 ++ .../rspeedy/core/src/config/dev/client.ts | 4 +- packages/rspeedy/core/src/config/dev/index.ts | 19 ++++-- packages/rspeedy/core/src/config/index.ts | 36 +++++------ .../rspeedy/core/src/config/loadConfig.ts | 11 ++++ .../core/src/config/output/css-modules.ts | 10 ++- .../core/src/config/output/dist-path.ts | 6 +- .../core/src/config/output/filename.ts | 61 ++++--------------- .../rspeedy/core/src/config/output/index.ts | 34 +++++++---- .../rspeedy/core/src/config/output/minify.ts | 10 +++ .../core/src/config/output/source-map.ts | 4 +- .../src/config/performance/build-cache.ts | 15 +---- .../src/config/performance/chunk-split.ts | 18 +++++- .../core/src/config/performance/index.ts | 12 +++- .../rspeedy/core/src/config/resolve/index.ts | 9 ++- .../rspeedy/core/src/config/server/index.ts | 24 ++++++-- .../core/src/config/source/decorators.ts | 2 + .../rspeedy/core/src/config/source/entry.ts | 6 +- .../rspeedy/core/src/config/source/index.ts | 26 ++++++-- .../core/src/config/source/transformImport.ts | 14 +++-- .../core/src/config/tools/css-extract.ts | 10 +++ .../core/src/config/tools/css-loader.ts | 18 ++++-- .../rspeedy/core/src/config/tools/index.ts | 15 +++++ 25 files changed, 232 insertions(+), 143 deletions(-) create mode 100644 .github/rspeedy-config-docs.instructions.md diff --git a/.github/rspeedy-config-docs.instructions.md b/.github/rspeedy-config-docs.instructions.md new file mode 100644 index 0000000000..107bcc0c3e --- /dev/null +++ b/.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. diff --git a/packages/rspeedy/core/etc/rspeedy.api.md b/packages/rspeedy/core/etc/rspeedy.api.md index 12c02c6fd4..990eb8f9db 100644 --- a/packages/rspeedy/core/etc/rspeedy.api.md +++ b/packages/rspeedy/core/etc/rspeedy.api.md @@ -220,9 +220,7 @@ export function loadConfig(loadConfigOptions: LoadConfigOptions): Promise:/` 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 * diff --git a/packages/rspeedy/core/src/config/index.ts b/packages/rspeedy/core/src/config/index.ts index 67e014f372..d73bc39de9 100644 --- a/packages/rspeedy/core/src/config/index.ts +++ b/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 `{ lynx: {} }` + * * @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. */ diff --git a/packages/rspeedy/core/src/config/loadConfig.ts b/packages/rspeedy/core/src/config/loadConfig.ts index 57936f3c13..c9aaffd0da 100644 --- a/packages/rspeedy/core/src/config/loadConfig.ts +++ b/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 } diff --git a/packages/rspeedy/core/src/config/output/css-modules.ts b/packages/rspeedy/core/src/config/output/css-modules.ts index 5a83ad3ec8..524c33f5b1 100644 --- a/packages/rspeedy/core/src/config/output/css-modules.ts +++ b/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: * diff --git a/packages/rspeedy/core/src/config/output/dist-path.ts b/packages/rspeedy/core/src/config/output/dist-path.ts index eb7f0ef5f2..9b27cd41f1 100644 --- a/packages/rspeedy/core/src/config/output/dist-path.ts +++ b/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 } diff --git a/packages/rspeedy/core/src/config/output/filename.ts b/packages/rspeedy/core/src/config/output/filename.ts index 55a2a28210..e988497c84 100644 --- a/packages/rspeedy/core/src/config/output/filename.ts +++ b/packages/rspeedy/core/src/config/output/filename.ts @@ -13,11 +13,9 @@ export interface Filename { /** * The name of the bundle files. * - * @remarks - * - * Default values: + * @defaultValue `'[name].[platform].bundle'` * - * - `'[name].[platform].bundle'` + * @remarks * * The following placeholder is supported: * @@ -66,11 +64,9 @@ export interface Filename { * * Use {@link Filename.bundle} instead. * - * @remarks - * - * Default values: + * @defaultValue `'[name].[platform].bundle'` * - * - `'[name].lynx.bundle'` + * @remarks * * The following placeholder is supported: * @@ -114,12 +110,7 @@ export 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 * @@ -149,11 +140,7 @@ export interface Filename { /** * The name of the CSS files. * - * @remarks - * - * Default values: - * - * - `'[name].css'` + * @defaultValue `'[name].css'` in development and `'[name].[contenthash:8].css'` in production * * @example * @@ -183,66 +170,42 @@ export 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 } diff --git a/packages/rspeedy/core/src/config/output/index.ts b/packages/rspeedy/core/src/config/output/index.ts index dddb8bf41a..24742c7e8b 100644 --- a/packages/rspeedy/core/src/config/output/index.ts +++ b/packages/rspeedy/core/src/config/output/index.ts @@ -17,6 +17,8 @@ export 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} @@ -44,11 +46,7 @@ export 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 * @@ -80,6 +78,8 @@ export 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}. @@ -126,6 +126,8 @@ export 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`. @@ -166,9 +168,7 @@ export 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 * @@ -230,6 +230,8 @@ export 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}. @@ -254,6 +256,8 @@ export 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}. @@ -274,6 +278,8 @@ export 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}. @@ -319,9 +325,9 @@ export interface Output { /** * The {@link Output.inlineScripts} option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`). * - * @remarks + * @defaultValue `true` unless `performance.chunkSplit.strategy` is explicitly set to a value other than `'all-in-one'`, in which case it defaults to `false` * - * 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`). * @@ -349,9 +355,9 @@ export 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. * @@ -368,6 +374,8 @@ export 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. @@ -384,6 +392,8 @@ export interface Output { /** * 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 } diff --git a/packages/rspeedy/core/src/config/output/minify.ts b/packages/rspeedy/core/src/config/output/minify.ts index 56c1b7a014..9998a62293 100644 --- a/packages/rspeedy/core/src/config/output/minify.ts +++ b/packages/rspeedy/core/src/config/output/minify.ts @@ -13,6 +13,8 @@ export 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. @@ -38,6 +40,8 @@ export 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. @@ -59,6 +63,8 @@ export 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}. @@ -89,6 +95,8 @@ export interface Minify { * {@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}. @@ -128,6 +136,8 @@ export interface Minify { * {@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}. diff --git a/packages/rspeedy/core/src/config/output/source-map.ts b/packages/rspeedy/core/src/config/output/source-map.ts index e25ede1cde..033a423222 100644 --- a/packages/rspeedy/core/src/config/output/source-map.ts +++ b/packages/rspeedy/core/src/config/output/source-map.ts @@ -12,9 +12,9 @@ export 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. * diff --git a/packages/rspeedy/core/src/config/performance/build-cache.ts b/packages/rspeedy/core/src/config/performance/build-cache.ts index 0363d15c94..0324e08626 100644 --- a/packages/rspeedy/core/src/config/performance/build-cache.ts +++ b/packages/rspeedy/core/src/config/performance/build-cache.ts @@ -43,20 +43,7 @@ export 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 * diff --git a/packages/rspeedy/core/src/config/performance/chunk-split.ts b/packages/rspeedy/core/src/config/performance/chunk-split.ts index e2195af8de..833119d0e2 100644 --- a/packages/rspeedy/core/src/config/performance/chunk-split.ts +++ b/packages/rspeedy/core/src/config/performance/chunk-split.ts @@ -12,9 +12,11 @@ export 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. * @@ -68,6 +70,8 @@ export interface ChunkSplit { /** * Custom Rspack chunk splitting config can be specified. * + * @defaultValue undefined + * * @example * * - Split `@lynx-js/react` and `react-router` into chunk `lib-react`. @@ -112,7 +116,9 @@ export 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 * @@ -132,7 +138,9 @@ export 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 * @@ -153,6 +161,8 @@ export interface ChunkSplitBySize { /** * {@inheritdoc ChunkSplit.override} + * + * @defaultValue undefined */ override?: Rspack.Configuration extends { optimization?: { @@ -176,6 +186,8 @@ export interface ChunkSplitCustom { /** * {@inheritdoc ChunkSplit.override} * + * @defaultValue undefined + * * @example * * - Split `@lynx-js/react` and `react-router` into chunk `lib-react`. diff --git a/packages/rspeedy/core/src/config/performance/index.ts b/packages/rspeedy/core/src/config/performance/index.ts index 0057b941d1..262480f9c0 100644 --- a/packages/rspeedy/core/src/config/performance/index.ts +++ b/packages/rspeedy/core/src/config/performance/index.ts @@ -35,6 +35,8 @@ export interface Performance { /** * Enable or configure persistent build cache. * + * @defaultValue false + * * @beta This feature is experimental and may be changed in the future. * * @example @@ -72,15 +74,15 @@ export interface Performance { /** * {@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 Enabled when `DEBUG` contains `rspeedy`; otherwise disabled * * @example * @@ -105,6 +107,8 @@ export interface Performance { /** * Whether to remove `console.[methodName]` in production build. * + * @defaultValue false + * * @example * * - Remove all `console` methods @@ -138,6 +142,8 @@ export 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. diff --git a/packages/rspeedy/core/src/config/resolve/index.ts b/packages/rspeedy/core/src/config/resolve/index.ts index 8af1d60c29..726ec961f7 100644 --- a/packages/rspeedy/core/src/config/resolve/index.ts +++ b/packages/rspeedy/core/src/config/resolve/index.ts @@ -13,6 +13,8 @@ export 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: @@ -94,6 +96,9 @@ export 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 @@ -119,6 +124,8 @@ export 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. @@ -144,7 +151,7 @@ export 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: * diff --git a/packages/rspeedy/core/src/config/server/index.ts b/packages/rspeedy/core/src/config/server/index.ts index df80920026..3434c55667 100644 --- a/packages/rspeedy/core/src/config/server/index.ts +++ b/packages/rspeedy/core/src/config/server/index.ts @@ -12,8 +12,10 @@ export 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://:/main.lynx.bundle` + * Users can access lynx bundle through `http://:/main.lynx.bundle` by default. * * If you want to access lynx bundle through `http://:/foo/main.lynx.bundle`, you can change `server.base` to `/foo` * @@ -35,7 +37,7 @@ export 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. * @@ -89,6 +91,8 @@ export 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). @@ -114,6 +118,8 @@ export interface Server { /** * Adds headers to all responses. * + * @defaultValue undefined + * * @example * * ```js @@ -132,8 +138,10 @@ export 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 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 * @@ -153,8 +161,10 @@ export interface Server { /** * Specify the port that the Rspeedy Server listens to. * + * @defaultValue 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 * @@ -174,6 +184,8 @@ export interface Server { /** * Configure proxy rules for the dev server or preview server to proxy requests to the specified service. * + * @defaultValue undefined + * * @example * * ```js @@ -193,7 +205,9 @@ export 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 } diff --git a/packages/rspeedy/core/src/config/source/decorators.ts b/packages/rspeedy/core/src/config/source/decorators.ts index d720b79db5..da20c40822 100644 --- a/packages/rspeedy/core/src/config/source/decorators.ts +++ b/packages/rspeedy/core/src/config/source/decorators.ts @@ -11,6 +11,8 @@ export 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?} diff --git a/packages/rspeedy/core/src/config/source/entry.ts b/packages/rspeedy/core/src/config/source/entry.ts index c844e60f39..de7215cd2e 100644 --- a/packages/rspeedy/core/src/config/source/entry.ts +++ b/packages/rspeedy/core/src/config/source/entry.ts @@ -16,10 +16,6 @@ export 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 @@ -28,6 +24,8 @@ export interface EntryDescription { /** * 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 diff --git a/packages/rspeedy/core/src/config/source/index.ts b/packages/rspeedy/core/src/config/source/index.ts index a2b8567d61..5dd6c7590d 100644 --- a/packages/rspeedy/core/src/config/source/index.ts +++ b/packages/rspeedy/core/src/config/source/index.ts @@ -17,11 +17,15 @@ export interface Source { * {@inheritdoc Resolve.alias} * * @deprecated - Use {@link Resolve.alias} instead. + * + * @defaultValue undefined */ alias?: Record | 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 * @@ -49,6 +53,8 @@ export interface Source { /** * Used to configure the decorators syntax. * + * @defaultValue undefined + * * @remarks * * See {@link Decorators.version} for more information. @@ -58,6 +64,8 @@ export interface Source { /** * The `define` options is used to define some values or expressions at compile time. * + * @defaultValue undefined + * * @example * * Using `define` for environment variables. @@ -156,10 +164,6 @@ export 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 @@ -226,6 +230,8 @@ export 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 @@ -288,6 +294,8 @@ export 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 @@ -365,6 +373,8 @@ export 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. @@ -387,6 +397,8 @@ export 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: @@ -421,7 +433,9 @@ export 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 * diff --git a/packages/rspeedy/core/src/config/source/transformImport.ts b/packages/rspeedy/core/src/config/source/transformImport.ts index 187a71a625..54dd2fa111 100644 --- a/packages/rspeedy/core/src/config/source/transformImport.ts +++ b/packages/rspeedy/core/src/config/source/transformImport.ts @@ -11,6 +11,8 @@ export interface TransformImport { /** * Whether to convert camelCase imports to kebab-case. * + * @defaultValue Rsbuild defaults this option to `true`. + * * @example * * - Input: @@ -26,7 +28,7 @@ export interface TransformImport { * import ButtonGroup from 'foo/button-group' * ``` * - * When set to `false` or `undefined`: + * When set to `false`: * ```js * import ButtonGroup from 'foo/ButtonGroup' * ``` @@ -36,6 +38,8 @@ export interface TransformImport { /** * Customize the transformed path. * + * @defaultValue undefined + * * @remarks * * You you can specify the format of the transformed path. @@ -67,9 +71,7 @@ export 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 * @@ -90,6 +92,8 @@ export interface TransformImport { /** * Whether to convert import statements to default imports. * + * @defaultValue Rsbuild defaults this option to `true`. + * * @example * * - Input: @@ -105,7 +109,7 @@ export interface TransformImport { * import Button from 'foo/button' * ``` * - * When set to `false` or `undefined`: + * When set to `false`: * ```js * import { Button } from 'foo/button' * ``` diff --git a/packages/rspeedy/core/src/config/tools/css-extract.ts b/packages/rspeedy/core/src/config/tools/css-extract.ts index 36a79b6f1c..99be3b0fbc 100644 --- a/packages/rspeedy/core/src/config/tools/css-extract.ts +++ b/packages/rspeedy/core/src/config/tools/css-extract.ts @@ -10,11 +10,15 @@ export 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 } @@ -58,6 +62,8 @@ export interface CssExtractRspackLoaderOptions { * ``` * * @public + * + * @defaultValue true */ esModule?: boolean | undefined } @@ -70,11 +76,15 @@ export interface CssExtractRspackLoaderOptions { export 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 } diff --git a/packages/rspeedy/core/src/config/tools/css-loader.ts b/packages/rspeedy/core/src/config/tools/css-loader.ts index 4eb1a85b94..48e8b2619d 100644 --- a/packages/rspeedy/core/src/config/tools/css-loader.ts +++ b/packages/rspeedy/core/src/config/tools/css-loader.ts @@ -12,13 +12,9 @@ export 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: - * - * - `1` when compiling CSS files + * @defaultValue `1` when compiling CSS files and `2` when compiling Sass or Less 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. */ @@ -27,6 +23,8 @@ export 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. @@ -88,22 +86,30 @@ export interface CssLoader { export 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` diff --git a/packages/rspeedy/core/src/config/tools/index.ts b/packages/rspeedy/core/src/config/tools/index.ts index c7376c9a12..4146227750 100644 --- a/packages/rspeedy/core/src/config/tools/index.ts +++ b/packages/rspeedy/core/src/config/tools/index.ts @@ -20,6 +20,8 @@ export 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 @@ -41,6 +43,8 @@ export 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: @@ -63,12 +67,19 @@ export interface Tools { /** * 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. @@ -92,6 +103,8 @@ export interface Tools { /** * The {@link Tools.rspack} controls the options of {@link https://www.rspack.dev/ | Rspack}. * + * @defaultValue undefined + * * @example * * - Use object config @@ -178,6 +191,8 @@ export interface Tools { /** * 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 } From 67d959458650475b41eb0fc377a9af60577a83f9 Mon Sep 17 00:00:00 2001 From: Qingyu Wang <40660121+colinaaa@users.noreply.github.com> Date: Sat, 11 Apr 2026 15:59:41 +0800 Subject: [PATCH 2/4] docs(rspeedy): clarify derived defaults --- packages/rspeedy/core/src/config/output/filename.ts | 2 +- packages/rspeedy/core/src/config/server/index.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/rspeedy/core/src/config/output/filename.ts b/packages/rspeedy/core/src/config/output/filename.ts index e988497c84..db760c50f0 100644 --- a/packages/rspeedy/core/src/config/output/filename.ts +++ b/packages/rspeedy/core/src/config/output/filename.ts @@ -140,7 +140,7 @@ export interface Filename { /** * The name of the CSS files. * - * @defaultValue `'[name].css'` in development and `'[name].[contenthash:8].css'` in production + * @defaultValue `'[name]/[name].css'` * * @example * diff --git a/packages/rspeedy/core/src/config/server/index.ts b/packages/rspeedy/core/src/config/server/index.ts index 3434c55667..09b6d0a578 100644 --- a/packages/rspeedy/core/src/config/server/index.ts +++ b/packages/rspeedy/core/src/config/server/index.ts @@ -161,7 +161,7 @@ export interface Server { /** * Specify the port that the Rspeedy Server listens to. * - * @defaultValue 3000 + * @defaultValue Rsbuild defaults this option to `3000`. * * @remarks * By default, the server automatically increments the port number when the configured port is occupied. From 4ed7052529a0048fb177924ec09f6558dfec4e2a Mon Sep 17 00:00:00 2001 From: Qingyu Wang <40660121+colinaaa@users.noreply.github.com> Date: Sat, 11 Apr 2026 16:01:50 +0800 Subject: [PATCH 3/4] docs(rspeedy): scope runtime default descriptions --- packages/rspeedy/core/src/config/index.ts | 2 +- packages/rspeedy/core/src/config/output/index.ts | 2 +- packages/rspeedy/core/src/config/performance/index.ts | 2 +- packages/rspeedy/core/src/config/server/index.ts | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/rspeedy/core/src/config/index.ts b/packages/rspeedy/core/src/config/index.ts index d73bc39de9..764efd761f 100644 --- a/packages/rspeedy/core/src/config/index.ts +++ b/packages/rspeedy/core/src/config/index.ts @@ -28,7 +28,7 @@ export interface Config { /** * The {@link Config.environments} option is used to set the output environment. * - * @defaultValue `{ lynx: {} }` + * @defaultValue When this option is unset, Rspeedy passes `{ lynx: {} }` to Rsbuild. * * @remarks * diff --git a/packages/rspeedy/core/src/config/output/index.ts b/packages/rspeedy/core/src/config/output/index.ts index 24742c7e8b..eecbe3eb21 100644 --- a/packages/rspeedy/core/src/config/output/index.ts +++ b/packages/rspeedy/core/src/config/output/index.ts @@ -325,7 +325,7 @@ export interface Output { /** * The {@link Output.inlineScripts} option controls whether to inline scripts into Lynx bundle (`.lynx.bundle`). * - * @defaultValue `true` unless `performance.chunkSplit.strategy` is explicitly set to a value other than `'all-in-one'`, in which case it defaults to `false` + * @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'`. * * @remarks * diff --git a/packages/rspeedy/core/src/config/performance/index.ts b/packages/rspeedy/core/src/config/performance/index.ts index 262480f9c0..c5eff5312b 100644 --- a/packages/rspeedy/core/src/config/performance/index.ts +++ b/packages/rspeedy/core/src/config/performance/index.ts @@ -82,7 +82,7 @@ export interface Performance { /** * 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. * - * @defaultValue Enabled when `DEBUG` contains `rspeedy`; otherwise disabled + * @defaultValue Rspeedy sets this to `true` when `DEBUG` contains `rspeedy`; otherwise it leaves the option unset. * * @example * diff --git a/packages/rspeedy/core/src/config/server/index.ts b/packages/rspeedy/core/src/config/server/index.ts index 09b6d0a578..3b0e4b9d30 100644 --- a/packages/rspeedy/core/src/config/server/index.ts +++ b/packages/rspeedy/core/src/config/server/index.ts @@ -141,7 +141,7 @@ export interface Server { * @defaultValue undefined * * @remarks - * During `rspeedy dev`, if `server.host` is unset, the dev plugin resolves dev-server-related URLs 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. + * 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 * From e11f89c9586f226cbafeec6152a9562c31d8297e Mon Sep 17 00:00:00 2001 From: Qingyu Wang <40660121+colinaaa@users.noreply.github.com> Date: Sat, 11 Apr 2026 16:06:20 +0800 Subject: [PATCH 4/4] chore: add empty changeset for rspeedy docs --- .changeset/crazy-women-raise.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .changeset/crazy-women-raise.md diff --git a/.changeset/crazy-women-raise.md b/.changeset/crazy-women-raise.md new file mode 100644 index 0000000000..853d812bb3 --- /dev/null +++ b/.changeset/crazy-women-raise.md @@ -0,0 +1,3 @@ +--- + +---