diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts index ae64e917d..96e14f4d6 100644 --- a/packages/core/src/types/config.ts +++ b/packages/core/src/types/config.ts @@ -1,5 +1,4 @@ import type { EnvironmentConfig, RsbuildConfig, Rspack } from '@rsbuild/core'; -import type { PluginDtsOptions } from 'rsbuild-plugin-dts'; import type { GetAsyncFunctionFromUnion } from './utils'; export type Format = 'esm' | 'cjs' | 'umd' | 'mf'; @@ -44,21 +43,67 @@ export type Syntax = | string[]; export type Dts = - | (Pick< - PluginDtsOptions, - 'bundle' | 'distPath' | 'abortOnError' | 'build' - > & { + | { + /** + * Whether to bundle the DTS files. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbundle} + */ + bundle?: boolean; + /** + * The output directory of DTS files. + * @defaultValue {@link https://lib.rsbuild.dev/config/lib/dts#default-value} + * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsdistpath} + */ + distPath?: string; + /** + * Whether to generate DTS files with building the project references. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbuild} + */ + build?: boolean; + /** + * Whether to abort the build process when an error occurs during DTS generation. + * @defaultValue `true` + * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsabortonerror} + */ + abortOnError?: boolean; + /** + * Whether to automatically set the DTS file extension based on the {@link format} option. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsautoextension} + */ autoExtension?: boolean; - }) + } | boolean; export type AutoExternal = | boolean | { + /** + * Whether to automatically externalize dependencies of type `dependencies`. + * @defaultValue `true` + * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaldependencies} + */ dependencies?: boolean; + /** + * Whether to automatically externalize dependencies of type `optionalDependencies`. + * @defaultValue `true` + * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaloptionaldependencies} + */ optionalDependencies?: boolean; - devDependencies?: boolean; + /** + * Whether to automatically externalize dependencies of type `peerDependencies`. + * @defaultValue `true` + * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternalpeerdependencies} + */ peerDependencies?: boolean; + /** + * Whether to automatically externalize dependencies of type `devDependencies`. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/auto-external#autoexternaldevdependencies} + */ + devDependencies?: boolean; }; export type BannerAndFooter = { @@ -68,12 +113,40 @@ export type BannerAndFooter = { }; export type Shims = { + /** + * Configure the shims for CommonJS output. + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimscjs} + */ cjs?: { + /** + * Whether to inject shims for the `import.meta.url` in CommonJS output. + * @defaultValue `true` + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimscjsimportmetaurl} + */ 'import.meta.url'?: boolean; }; + /** + * Configure the shims for ESM output. + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm} + */ esm?: { + /** + * Whether to inject shims for the global `__filename` of CommonJS in ESM output. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm__filename} + */ __filename?: boolean; + /** + * Whether to inject shims for the global `__dirname` of CommonJS in ESM output. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesm__dirname} + */ __dirname?: boolean; + /** + * Whether to inject shims for the global `require` of CommonJS in ESM output. + * @defaultValue `false` + * @see {@link https://lib.rsbuild.dev/config/lib/shims#shimsesmrequire} + */ require?: boolean; }; }; @@ -85,7 +158,7 @@ export type JsRedirect = { */ path?: boolean; /** - * Whether to automatically add the file extension to import paths based on the JavaScript output files. + * Whether to automatically redirect the file extension to import paths based on the JavaScript output files. * @defaultValue `true` */ extension?: boolean; @@ -98,7 +171,7 @@ export type StyleRedirect = { */ path?: boolean; /** - * Whether to automatically add the file extension to import paths based on the style output files. + * Whether to automatically redirect the file extension to import paths based on the style output files. * @defaultValue `true` */ extension?: boolean; @@ -113,7 +186,7 @@ type DtsRedirect = { export type Redirect = { /** Controls the redirect of the import paths of output JavaScript files. */ js?: JsRedirect; - /** Whether to redirect the import path of the style file. */ + /** Controls the redirect of the import paths of output style files. */ style?: StyleRedirect; // TODO: support other redirects // asset?: boolean; diff --git a/packages/plugin-dts/README.md b/packages/plugin-dts/README.md index 0ac5172a6..8da144229 100644 --- a/packages/plugin-dts/README.md +++ b/packages/plugin-dts/README.md @@ -75,7 +75,7 @@ pluginDts({ - **Type:** `boolean` - **Default:** `false` -Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. +Whether to generate DTS files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements. diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx index adc51d0d0..95b14c49d 100644 --- a/website/docs/en/config/lib/dts.mdx +++ b/website/docs/en/config/lib/dts.mdx @@ -130,7 +130,7 @@ export default { - **Type:** `boolean` - **Default:** `false` -Determines whether to generate DTS files while building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. +Whether to generate DTS files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details. ::: note diff --git a/website/docs/en/config/lib/redirect.mdx b/website/docs/en/config/lib/redirect.mdx index f5ebe0f38..ba18898e0 100644 --- a/website/docs/en/config/lib/redirect.mdx +++ b/website/docs/en/config/lib/redirect.mdx @@ -95,7 +95,7 @@ When set to `false`, the import path will not be effected by [resolve.alias](/co ### redirect.js.extension -Whether to automatically add the file extension to import paths based on the JavaScript output files. +Whether to automatically redirect the file extension to import paths based on the JavaScript output files. - **Type:** `boolean` - **Default:** `true` @@ -106,9 +106,11 @@ When set to `false`, the file extension will remain unchanged from the original ## redirect.style +Controls the redirect of the import paths of output style files. + ### redirect.style.path -Whether to automatically redirect the import path when importing style files, the rules are the same as [redirect.js.path](/config/lib/redirect#redirectjspath). +Whether to automatically redirect the import paths of style output files, the rules are the same as [redirect.js.path](/config/lib/redirect#redirectjspath). - **Type:** `boolean` - **Default:** `true` @@ -137,7 +139,7 @@ import styles from '../foo.css'; // expected output of './dist/utils/index.js' ### redirect.style.extension -Whether to redirect style file extensions. +Whether to automatically redirect the file extension to import paths based on the style output files. - **Type:** `boolean` - **Default:** `true` diff --git a/website/docs/en/config/lib/shims.mdx b/website/docs/en/config/lib/shims.mdx index f301294a4..8be58e19f 100644 --- a/website/docs/en/config/lib/shims.mdx +++ b/website/docs/en/config/lib/shims.mdx @@ -42,6 +42,8 @@ Set the fields to `true` to enable the corresponding shims for CommonJS output. ### shims.cjs['import.meta.url'] +Whether to inject shims for the `import.meta.url` in CommonJS output. + - **Default:** `true` Options: @@ -82,7 +84,7 @@ Set the fields to `true` to enable the corresponding shims for ESM output. ### shims.esm.\_\_filename -Whether to shim the global `__filename` of CommonJS in ESM output. +Whether to inject shims for the global `__filename` of CommonJS in ESM output. - **Default:** `false` @@ -112,7 +114,7 @@ Options: ### shims.esm.\_\_dirname -Whether to shim the global `__dirname` of CommonJS in ESM output. +Whether to inject shims for the global `__dirname` of CommonJS in ESM output. - **Default:** `false` @@ -141,7 +143,7 @@ Options: ### shims.esm.require -Whether to shim the global `require` of CommonJS in ESM output. +Whether to inject shims for the global `require` of CommonJS in ESM output. - **Default:** `false` diff --git a/website/docs/zh/config/lib/dts.mdx b/website/docs/zh/config/lib/dts.mdx index 58d15d1fc..7893d637f 100644 --- a/website/docs/zh/config/lib/dts.mdx +++ b/website/docs/zh/config/lib/dts.mdx @@ -130,7 +130,7 @@ export default { - **类型:** `boolean` - **默认值:** `false` -决定是否在构建项目引用时生成 DTS 文件。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。 +是否在生成 DTS 文件时构建项目的 references。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。 ::: note diff --git a/website/docs/zh/config/lib/redirect.mdx b/website/docs/zh/config/lib/redirect.mdx index c0f3bcf61..b75d6d0eb 100644 --- a/website/docs/zh/config/lib/redirect.mdx +++ b/website/docs/zh/config/lib/redirect.mdx @@ -6,7 +6,7 @@ overviewHeaders: [2, 3] :::info -`redirect` 是 bundleless 模式(将 [lib.bundle](/config/lib/bundle) 设置为 `false`)的特定配置。在 bundle 模式下不会生效,因为所有输出文件都被打包成一个文件。所以,导入路径不存在因而不需要重定向。 +`redirect` 是 bundleless 模式(将 [lib.bundle](/config/lib/bundle) 设置为 `false`)的特定配置。在 bundle 模式下不会生效,因为所有产物文件都被打包成一个文件。所以,导入路径不存在因而不需要重定向。 由于 bundleless 模式仍在开发中,未来将引入更多的重定向配置。 @@ -46,13 +46,13 @@ const defaultRedirect = { }; ``` -配置输出文件中导入路径的重定向。在 bundleless 模式下,通常需要使用别名或自动添加 ESM 产物的后缀。`redirect` 配置旨在解决这些问题。 +配置产物文件中导入路径的重定向。在 bundleless 模式下,通常需要使用别名或自动添加 ESM 产物的后缀。`redirect` 配置旨在解决这些问题。 常见的需要 redirect 的场景: - 自动将 tsconfig.json 中 `compilerOptions.paths` 转换为正确的相对路径 - 例如,在 tsconfig.json 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }`,输出文件将被重定向到正确的相对路径: + 例如,在 tsconfig.json 中将 `compilerOptions.paths` 设置为 `{ "@/*": ["src/*"] }`,产物文件将被重定向到正确的相对路径: ```ts import { foo } from '@/foo'; // './src/bar.ts' 的源码 ↓ @@ -64,7 +64,7 @@ const defaultRedirect = { - 自动添加文件后缀 - 对于在 Node.js 中运行的 ESM 产物,必须指定模块导入的完整路径才能正确加载。Rslib 将根据输出文件自动添加后缀。 + 对于在 Node.js 中运行的 ESM 产物,必须指定模块导入的完整路径才能正确加载。Rslib 将根产物文件自动添加后缀。 ```ts import { foo } from './foo'; // './src/bar.ts' 的源码 ↓ @@ -76,7 +76,7 @@ const defaultRedirect = { ## redirect.js -控制输出 JavaScript 文件导入路径的重定向。 +控制 JavaScript 产物文件导入路径的重定向。 :::warning 当 [output.externals](/config/rsbuild/output#outputexternals) 被配置且请求被匹配时,`redirect.js.path` 和 `redirect.js.extension` 都不会生效,最终重写的请求路径将完全由 [output.externals](/config/rsbuild/output#outputexternals) 控制。 @@ -84,31 +84,33 @@ const defaultRedirect = { ### redirect.js.path -是否自动重定向 JavaScript 输出文件的导入路径。 +是否自动重定向 JavaScript 产物文件的导入路径。 - **类型:** `boolean` - **默认值:** `true` -当设置为 `true` 时,[resolve.alias](/config/rsbuild/resolve#resolvealias) 和 [resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 将生效并应用于输出文件的重写导入路径。对于 TypeScript 项目,您只需在 tsconfig.json 文件中配置 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths)。 +当设置为 `true` 时,[resolve.alias](/config/rsbuild/resolve#resolvealias) 和 [resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 将生效并应用于产物文件的重写导入路径。对于 TypeScript 项目,您只需在 tsconfig.json 文件中配置 [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths)。 当设置为 `false` 时,导入路径将不受 [resolve.alias](/config/rsbuild/resolve#resolvealias)、[resolve.aliasStrategy](/config/rsbuild/resolve#aliasstrategy) 和 tsconfig.json 的影响。 ### redirect.js.extension -是否根据 JavaScript 输出文件自动添加文件扩展名到导入路径。 +是否根据 JavaScript 产物文件自动重定向文件扩展名到导入路径。 - **类型:** `boolean` - **默认值:** `true` -当设置为 `true` 时,无论原始扩展名或导入路径中是否指定,文件扩展名都将自动添加到输出文件的重写导入路径中。 +当设置为 `true` 时,无论原始扩展名或导入路径中是否指定,文件扩展名都将自动添加到产物文件的重写导入路径中。 当设置为 `false` 时,文件扩展名将保持原始导入路径中的不变(无论是否指定或指定为任意值)。 ## redirect.style +控制样式产物文件导入路径的重定向。 + ### redirect.style.path -导入样式文件时是否自动重定向导入路径,规则与 [redirect.js.path](/config/lib/redirect#redirectjspath) 相同。 +是否自动重定向样式产物文件的导入路径,规则与 [redirect.js.path](/config/lib/redirect#redirectjspath) 相同。 - **类型:** `boolean` - **默认值:** `true` @@ -137,12 +139,12 @@ import styles from '../foo.css'; // './dist/utils/index.js' 预期生成的代 ### redirect.style.extension -是否重定向样式文件的扩展名。 +是否根据样式产物文件自动重定向文件扩展名到导入路径。 - **类型:** `boolean` - **默认值:** `true` -当设置为 `true` 时,导入普通样式文件时,路径将被重写为 `.css` 文件,导入 [CSS Modules](/config/rsbuild/output#outputcssmodules) 时,路径将被重写为到对应的 JavaScript 输出文件。 +当设置为 `true` 时,导入普通样式文件时,路径将被重写为 `.css` 文件,导入 [CSS Modules](/config/rsbuild/output#outputcssmodules) 时,路径将被重写为到对应的 JavaScript 产物文件。 当设置为 `false` 时,文件扩展名将保持原始导入路径中的不变。 diff --git a/website/docs/zh/config/lib/shims.mdx b/website/docs/zh/config/lib/shims.mdx index 85acb6cd2..d62616243 100644 --- a/website/docs/zh/config/lib/shims.mdx +++ b/website/docs/zh/config/lib/shims.mdx @@ -34,14 +34,16 @@ const defaultShims = { }; ``` -配置 CommonJS 和 ESM 输出的 [shims(垫片)](https://developer.mozilla.org/zh-CN/docs/Glossary/Shim)。 +配置 CommonJS 和 ESM 产物的 [shims(垫片)](https://developer.mozilla.org/zh-CN/docs/Glossary/Shim)。 ## shims.cjs -将字段设置为 `true` 以启用对应的 CommonJS 输出 shims。 +将字段设置为 `true` 以启用对应的 CommonJS 产物 shims。 ### shims.cjs['import.meta.url'] +是否在 CommonJS 产物为 `import.meta.url` 注入 shims。 + - **默认值:** `true` 选项: @@ -55,7 +57,7 @@ const defaultShims = { const buffer = readFileSync(new URL('./data.proto', import.meta.url)); ``` - 将被转换为以下 CJS 输出代码: + 将被转换为以下 CJS 产物代码: ```js const { readFileSync } = require('fs'); @@ -78,11 +80,11 @@ const defaultShims = { ## shims.esm -将字段设置为 `true` 以启用对应的 ESM 输出 shims。 +将字段设置为 `true` 以启用对应的 ESM 产物 shims。 ### shims.esm.\_\_filename -是否在 ESM 输出中为 CommonJS 的全局 `__filename` 注入 shims。 +是否在 ESM 产物中为 CommonJS 的全局 `__filename` 注入 shims。 - **默认值:** `false` @@ -96,7 +98,7 @@ const defaultShims = { console.log(__filename); ``` - ESM 输出将被转换为: + ESM 产物将被转换为: ```js import { fileURLToPath as __webpack_fileURLToPath__ } from 'url'; @@ -112,7 +114,7 @@ const defaultShims = { ### shims.esm.\_\_dirname -是否在 ESM 输出中为 CommonJS 的全局 `__dirname` 注入 shims。 +是否在 ESM 产物中为 CommonJS 的全局 `__dirname` 注入 shims。 - **默认值:** `false` @@ -126,7 +128,7 @@ const defaultShims = { console.log(__dirname); ``` - ESM 输出将被转换为: + ESM 产物将被转换为: ```js import { fileURLToPath as __webpack_fileURLToPath__ } from 'url'; @@ -141,13 +143,13 @@ const defaultShims = { ### shims.esm.require -是否在 ESM 输出中为 CommonJS 的全局 `require` 注入 shims。 +是否在 ESM 产物中为 CommonJS 的全局 `require` 注入 shims。 - **默认值:** `false` 选项: -- `true`:当 [format](/config/lib/format) 为 `esm` 时,在输出的开头将会创建一个由 `createRequire` 生成的 `require`,可以在源代码中像 CommonJS 的全局 `require` 一样使用。 +- `true`:当 [format](/config/lib/format) 为 `esm` 时,在产物的开头将会创建一个由 `createRequire` 生成的 `require`,可以在源代码中像 CommonJS 的全局 `require` 一样使用。 例如,给定以下源代码: @@ -163,7 +165,7 @@ const defaultShims = { lazyFn('./other.js', require); ``` - ESM 输出将被转换为: + ESM 产物将被转换为: ```js import __rslib_shim_module__ from 'module';