diff --git a/packages/core/src/types/config/index.ts b/packages/core/src/types/config/index.ts index 72d2f461d..5ae702680 100644 --- a/packages/core/src/types/config/index.ts +++ b/packages/core/src/types/config/index.ts @@ -132,13 +132,13 @@ export interface LibConfig extends RsbuildConfig { */ externalHelpers?: boolean; /** - * Inject content into the top of each JS, CSS or DTS file. + * Inject content into the top of each JavaScript, CSS or DTS file. * @defaultValue `{}` * @see {@link https://lib.rsbuild.dev/config/lib/banner} */ banner?: BannerAndFooter; /** - * Inject content into the bottom of each JS, CSS or DTS file. + * Inject content into the bottom of each JavaScript, CSS or DTS file. * @defaultValue `{}` * @see {@link https://lib.rsbuild.dev/config/lib/footer} */ diff --git a/website/docs/en/config/lib/auto-extension.mdx b/website/docs/en/config/lib/auto-extension.mdx index 345bf06de..8e7fb07c0 100644 --- a/website/docs/en/config/lib/auto-extension.mdx +++ b/website/docs/en/config/lib/auto-extension.mdx @@ -15,7 +15,7 @@ By default that when `autoExtension` is set to `true`, the file extension will b :::warning -When [bundle](/config/lib/bundle) is set to `false` that as known as bundleless mode, you should write full path instead of ignoring directory indexes (e.g. `'./foo/index.js'`) in source code. +When [bundle](/config/lib/bundle) is set to `false` that as known as bundleless mode, you should write full path instead of ignoring directory indexes (e.g. using `'./foo'` as a shorthand for `'./foo/index.js'`) in source code. For example, if `foo` is a folder, you need to rewrite `import * from './foo'` to `import * from './foo/index'`. diff --git a/website/docs/en/config/lib/auto-external.mdx b/website/docs/en/config/lib/auto-external.mdx index cd9dc0c53..7660db9e0 100644 --- a/website/docs/en/config/lib/auto-external.mdx +++ b/website/docs/en/config/lib/auto-external.mdx @@ -28,28 +28,28 @@ Whether to automatically externalize dependencies of different dependency types - **Type:** `boolean` - **Default:** `true` -Whether to externalize dependencies of type `dependencies`. +Whether to automatically externalize dependencies of type `dependencies`. ### autoExternal.optionalDependencies - **Type:** `boolean` - **Default:** `true` -Whether to externalize dependencies of type `optionalDependencies`. +Whether to automatically externalize dependencies of type `optionalDependencies`. ### autoExternal.peerDependencies - **Type:** `boolean` - **Default:** `true` -Whether to externalize dependencies of type `peerDependencies`. +Whether to automatically externalize dependencies of type `peerDependencies`. ### autoExternal.devDependencies - **Type:** `boolean` - **Default:** `false` -Whether to bundle dependencies of type `devDependencies`. +Whether to automatically externalize dependencies of type `devDependencies`. ## Default Value diff --git a/website/docs/en/config/lib/banner.mdx b/website/docs/en/config/lib/banner.mdx index 5e229341e..7dd1bb9da 100644 --- a/website/docs/en/config/lib/banner.mdx +++ b/website/docs/en/config/lib/banner.mdx @@ -16,7 +16,7 @@ type Banner = { - **Default:** `{}` -Inject content into the top of each JS, CSS or DTS file. +Inject content into the top of each JavaScript, CSS or DTS output file. ## Object Type @@ -25,25 +25,25 @@ Inject content into the top of each JS, CSS or DTS file. - **Type:** `string` - **Default:** `undefined` -Inject content into the top of each JS file. +Inject content into the top of each JavaScript output file. ### banner.css - **Type:** `string` - **Default:** `undefined` -Inject content into the top of each CSS file. +Inject content into the top of each CSS output file. ### banner.dts - **Type:** `string` - **Default:** `undefined` -Inject content into the top of each DTS file. +Inject content into the top of each DTS output file. ## Notice -The banner content in JS/CSS file is based on the [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) of Rspack. You should notice the following points: +The banner content in JavaScript and CSS file is based on the [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) of Rspack. You should notice the following points: - `raw: true` is enabled by default, so the banner content will be injected as a raw string instead of wrapping in a comment. So if you want to inject a comment, you should add `/*` and `*/` or other comment syntax by yourself. - The `stage` option is set to the stage after the JavaScript and CSS files are optimized, thus preventing the banner content from being optimized away. @@ -73,6 +73,6 @@ export default { :::warning -The banner content in DTS files is handled differently from JS/CSS files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it. +The banner content in DTS files is handled differently from JavaScript and CSS output files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it. ::: diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx index a102d8463..adc51d0d0 100644 --- a/website/docs/en/config/lib/dts.mdx +++ b/website/docs/en/config/lib/dts.mdx @@ -65,7 +65,7 @@ Whether to bundle the DTS files. If you want to [bundle DTS](/guide/advanced/dts#bundle-dts) files, you should: -1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files. +1. Install [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) as a development dependency, which is the underlying tool used for bundling DTS files. import { PackageManagerTabs } from '@theme'; @@ -88,7 +88,7 @@ export default { ::: note -[@microsoft/api-extractor](https://github.com/microsoft/rushstack/tree/main/apps/api-extractor) only supports bundle DTS for single entry. If you want to generate bundle DTS for multiple entries, you can add extra lib configuration in [lib](/config/lib/) field to split multiple entries into multiple lib configurations. +[@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) only supports bundle DTS for single entry. If you want to generate bundle DTS for multiple entries, you can add extra lib configuration in [lib](/config/lib/) field to split multiple entries into multiple lib configurations. ::: diff --git a/website/docs/en/config/lib/external-helpers.mdx b/website/docs/en/config/lib/external-helpers.mdx index 776137f30..e36c8166c 100644 --- a/website/docs/en/config/lib/external-helpers.mdx +++ b/website/docs/en/config/lib/external-helpers.mdx @@ -11,7 +11,7 @@ When `externalHelpers` set to `true`, the output JavaScript will import helper f ::: note -Make sure to declare the `@swc/helpers` in `dependencies` field of `package.json`. +Make sure to declare and install `@swc/helpers` in `dependencies` field of `package.json`. ::: @@ -39,9 +39,9 @@ export default { }; ``` -Below is the output JavaScript file: +Below is the output JavaScript file, the highlighted code is the inlined helper functions: -```js title="index.js" +```js title="index.js" {1-18} function _class_call_check(instance, Constructor) { if (!(instance instanceof Constructor)) throw new TypeError('Cannot call a class as a function'); @@ -88,7 +88,7 @@ export default { }; ``` -Below is the output JavaScript file: +Below is the output JavaScript file, the highlighted code is importing helper functions: ```js title="index.js" {1-2} import * as __WEBPACK_EXTERNAL_MODULE__swc_helpers_class_call_check__ from '@swc/helpers/_/_class_call_check'; diff --git a/website/docs/en/config/lib/footer.mdx b/website/docs/en/config/lib/footer.mdx index e323cb44c..62cb12682 100644 --- a/website/docs/en/config/lib/footer.mdx +++ b/website/docs/en/config/lib/footer.mdx @@ -16,7 +16,7 @@ type Footer = { - **Default:** `{}` -Inject content into the bottom of each JS, CSS or DTS file. +Inject content into the bottom of each JavaScript, CSS or DTS file. ## Object Type @@ -25,25 +25,25 @@ Inject content into the bottom of each JS, CSS or DTS file. - **Type:** `string` - **Default:** `undefined` -Inject content into the bottom of each JS file. +Inject content into the bottom of each JavaScript output file. ### footer.css - **Type:** `string` - **Default:** `undefined` -Inject content into the bottom of each CSS file. +Inject content into the bottom of each CSS output file. ### footer.dts - **Type:** `string` - **Default:** `undefined` -Inject content into the bottom of each DTS file. +Inject content into the bottom of each DTS output file. ## Notice -The footer content in JS/CSS file is based on the [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) of Rspack. You should notice the following points: +The footer content in JavaScript and CSS file is based on the [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) of Rspack. You should notice the following points: - `raw: true` is enabled by default, so the footer content will be injected as a raw string instead of wrapping in a comment. So if you want to inject a comment, you should add `/*` and `*/` or other comment syntax by yourself. - The `stage` option is set to the stage after the JavaScript and CSS files are optimized, thus preventing the footer content from being optimized away. @@ -74,6 +74,6 @@ export default { :::warning -The footer content in DTS files is handled differently from JS/CSS files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it. +The footer content in DTS files is handled differently from JavaScript and CSS files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it. ::: diff --git a/website/docs/en/config/lib/format.mdx b/website/docs/en/config/lib/format.mdx index 2247767ce..b95d26d3a 100644 --- a/website/docs/en/config/lib/format.mdx +++ b/website/docs/en/config/lib/format.mdx @@ -1,12 +1,10 @@ # lib.format - **Type:** `'esm' | 'cjs' | 'umd' | 'mf'` - - **Default:** `undefined` - - **Required**: true -Specify the output format for the generated JavaScript files. +Specify the output format for the generated JavaScript output files. See [Output Format](/guide/basic/output-format) and [Module Federation](/guide/advanced/module-federation) for more details. diff --git a/website/docs/en/config/lib/shims.mdx b/website/docs/en/config/lib/shims.mdx index bd4994d02..f301294a4 100644 --- a/website/docs/en/config/lib/shims.mdx +++ b/website/docs/en/config/lib/shims.mdx @@ -34,7 +34,7 @@ const defaultShims = { }; ``` -Configure the shims for CommonJS and ESM output. +Configure the [shims](https://developer.mozilla.org/en-US/docs/Glossary/Shim) for CommonJS and ESM output. ## shims.cjs diff --git a/website/docs/en/config/lib/syntax.mdx b/website/docs/en/config/lib/syntax.mdx index 391697351..6e26f9de9 100644 --- a/website/docs/en/config/lib/syntax.mdx +++ b/website/docs/en/config/lib/syntax.mdx @@ -42,7 +42,7 @@ export default { ## Set Browserslist Query -You can also set the Browserslist query, such as `last 2 versions`, `> 1%`, `node >= 16`, `chrome >= 80`, etc. +You can also set the [Browserslist query](https://browsersl.ist/), such as `last 2 versions`, `> 1%`, `node >= 16`, `chrome >= 80`, etc. ```ts title="rslib.config.ts" export default { @@ -56,7 +56,7 @@ export default { ## Mix ECMAScript Version and Browserslist Query -You can also mix ECMAScript version and Browserslist query, such as `es2015` and `node 20`. We will turn ECMAScript Version into Browserslist query, and then merge them together. +You can also mix ECMAScript version and Browserslist query, such as `es2015` and `node 20`. Rslib will turn ECMAScript Version into Browserslist query, and then merge them together. ```ts title="rslib.config.ts" export default { diff --git a/website/docs/zh/config/lib/auto-extension.mdx b/website/docs/zh/config/lib/auto-extension.mdx index 7d736367a..c5ba9bbcb 100644 --- a/website/docs/zh/config/lib/auto-extension.mdx +++ b/website/docs/zh/config/lib/auto-extension.mdx @@ -1 +1,52 @@ # lib.autoExtension + +- **类型:** `boolean` +- **默认值:** `true` + +是否根据 [`format`](/config/lib/format) 配置项自动设置 JavaScript 输出文件的扩展名。 + +## 默认扩展名 + +默认情况下,当 `autoExtension` 设置为 `true` 时,文件扩展名将会是: + +- 当 `package.json` 中设置 `type: module` 时,`esm` 格式使用 `.js`,`cjs` 格式使用 `.cjs`。 + +- 当 `package.json` 中设置 `type: commonjs` 或没有 `type` 字段时,`cjs` 格式使用 `.js`,`esm` 格式使用 `.mjs`。 + +:::warning + +当 [bundle](/config/lib/bundle) 设置为 `false`(即 bundleless 模式)时,你需要在源代码中写完整的路径,而不是省略目录索引(例如,用 `'./foo'` 作为 `'./foo/index.js'` 的简写)。 + +举例来说,如果 `foo` 是一个文件夹,你需要将 `import * from './foo'` 改写为 `import * from './foo/index'`。 + +::: + +当 `autoExtension` 设置为 `false` 时,文件扩展名将默认为 `.js`。 + +## 自定义扩展名 + +你可以将 `autoExtension` 设置为 `false`,并使用 [output.filename](https://rsbuild.dev/zh/config/output/filename) 来自定义 JavaScript 输出文件。 + +```ts title="rslib.config.ts" +export default defineConfig({ + lib: [ + { + format: 'cjs', + autoExtension: false, + output: { + filename: { + js: '[name].cjs', + }, + }, + }, + { + format: 'esm', + output: { + filename: { + js: '[name].mjs', + }, + }, + }, + ], +}); +``` diff --git a/website/docs/zh/config/lib/auto-external.mdx b/website/docs/zh/config/lib/auto-external.mdx index 5a8277b88..9950146b0 100644 --- a/website/docs/zh/config/lib/auto-external.mdx +++ b/website/docs/zh/config/lib/auto-external.mdx @@ -3,3 +3,117 @@ overviewHeaders: [2, 3] --- # lib.autoExternal + +- **类型:** + +```ts +type AutoExternal = + | boolean + | { + dependencies?: boolean; + optionalDependencies?: boolean; + devDependencies?: boolean; + peerDependencies?: boolean; + }; +``` + +- **默认值:** `true` + +是否自动对不同依赖类型的依赖进行外部化处理,不将其打包。 + +## 对象类型 + +### autoExternal.dependencies + +- **类型:** `boolean` +- **默认值:** `true` + +是否自动外部化 `dependencies` 类型的依赖。 + +### autoExternal.optionalDependencies + +- **类型:** `boolean` +- **默认值:** `true` + +是否自动外部化 `optionalDependencies` 类型的依赖。 + +### autoExternal.peerDependencies + +- **类型:** `boolean` +- **默认值:** `true` + +是否自动外部化 `peerDependencies` 类型的依赖。 + +### autoExternal.devDependencies + +- **类型:** `boolean` +- **默认值:** `false` + +是否自动外部化 `devDependencies` 类型的依赖。 + +## 默认值 + +`autoExternal` 的默认值为 `true`,意味着以下依赖类型**不会被打包**: + +- `dependencies` +- `optionalDependencies` +- `peerDependencies` + +而以下依赖类型会被**打包**: + +- `devDependencies` + +此配置等同于下面的对象类型: + +```ts +export default { + lib: [ + { + format: 'esm', + autoExternal: { + dependencies: true, + optionalDependencies: true, + peerDependencies: true, + devDependencies: false, + }, + }, + ], +}; +``` + +## 示例 + +### 自定义外部化的依赖类型 + +要禁用特定类型依赖的处理,你可以将 `autoExternal` 配置为一个对象,如下所示: + +```ts title="rslib.config.ts" +export default { + lib: [ + { + format: 'esm', + autoExternal: { + dependencies: false, + peerDependencies: false, + }, + }, + ], +}; +``` + +### 禁用默认行为 + +如果你想禁用默认行为,可以将 `autoExternal` 设置为 `false`: + +```ts title="rslib.config.ts" +export default { + lib: [ + { + format: 'esm', + autoExternal: false, + }, + ], +}; +``` + +关于第三方依赖处理的更多细节,请参考 [处理第三方依赖](/guide/advanced/third-party-deps)。 diff --git a/website/docs/zh/config/lib/banner.mdx b/website/docs/zh/config/lib/banner.mdx index 411e019eb..5c88f7bb9 100644 --- a/website/docs/zh/config/lib/banner.mdx +++ b/website/docs/zh/config/lib/banner.mdx @@ -3,3 +3,76 @@ overviewHeaders: [2, 3] --- # lib.banner + +- **类型:** + +```ts +type Banner = { + js?: string; + css?: string; + dts?: string; +}; +``` + +- **默认值:** `{}` + +在每个 JavaScript、CSS 或 DTS 输出文件顶部注入内容。 + +## 对象类型 + +### banner.js + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 JavaScript 输出文件顶部注入内容。 + +### banner.css + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 CSS 输出文件顶部注入内容。 + +### banner.dts + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 DTS 输出文件顶部注入内容。 + +## 注意事项 + +JavaScript 和 CSS 文件中的 banner 内容是基于 Rspack 的 [BannerPlugin](https://rspack.dev/zh/plugins/webpack/banner-plugin) 实现的。你需要注意以下几点: + +- 默认启用了 `raw: true`,所以 banner 内容会作为原始字符串注入,而不是包裹在注释中。因此如果你想注入注释,需要自己添加 `/*` 和 `*/` 或其他注释语法。 +- `stage` 选项被设置在 JavaScript 和 CSS 文件优化之后的阶段,从而防止 banner 内容被优化掉。 + +## 自定义 Banner 内容 + +如果上述默认设置无法满足你的需求,你可以通过 `tools.rspack.plugins` 自定义添加一个带有相应选项的 [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) 实例。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + // ... + tools: { + rspack: { + plugins: [ + new rspack.BannerPlugin({ + // ... options + }), + ], + }, + }, + }, + ], +}; +``` + +:::warning + +DTS 文件中的 banner 内容处理方式与 JavaScript 和 CSS 输出文件不同。它是直接使用文件系统 API 写入的,所以设置 `BannerPlugin` 不会对其产生影响。 + +::: diff --git a/website/docs/zh/config/lib/bundle.mdx b/website/docs/zh/config/lib/bundle.mdx index da9ef7c32..e612571f3 100644 --- a/website/docs/zh/config/lib/bundle.mdx +++ b/website/docs/zh/config/lib/bundle.mdx @@ -1 +1,144 @@ # lib.bundle + +- **类型:** `boolean` +- **默认值:** `undefined` + +指定是否打包库,当 `bundle` 设置为 `true` 时称为 bundle 模式,设置为 `false` 时称为 bundleless 模式。更多详情请参见 [bundle / bundleless](/guide/basic/output-structure#bundle--bundleless)。 + +::: warning +无打包模式尚未完全支持,某些功能如 [资源](/guide/advanced/assets) 可能无法正常工作。 +::: + +## 设置入口 + +我们需要为构建指定入口文件。 + +### bundle: true + +当 `bundle` 设置为 `true` 时,入口需要设置为入口文件。默认入口为 `src/index.(ts|js|tsx|jsx|mjs|cjs)`。你需要确保入口文件存在,或通过 [source.entry](https://rsbuild.dev/zh/config/source/entry) 配置自定义入口。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + format: 'cjs', + bundle: true, + }, + ], + source: { + entry: { + index: './foo/index.ts', + }, + }, +}; +``` + +### bundle: false + +当 `bundle` 设置为 `false` 时,入口需要设置为 [glob 模式](https://github.com/micromatch/picomatch#globbing-features) 以包含所有文件。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + format: 'cjs', + bundle: false, + }, + ], + source: { + entry: { + index: './src/**', + }, + }, +}; +``` + +你也可以使用感叹号来排除一些文件。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + format: 'cjs', + bundle: false, + }, + ], + source: { + entry: { + index: ['./src/**', '!**/foo.*'], + }, + }, +}; +``` + +## Example + +对于以下的源代码文件结构: + +``` +. +├── src +│ ├── index.ts +│ ├── foo.ts +│ └── bar.ts +└── package.json +``` + +### bundle: true + +```ts title="rslib.config.ts" +export default defineConfig({ + lib: [ + { + format: 'cjs', + bundle: true, + }, + ], +}); +``` + +当 `bundle` 设置为 `true` 时,也称为 bundle 模式,Rslib 会将库打包成单个文件。 + +```diff + . ++ ├── dist ++ │ └── index.js + ├── src + │ ├── index.ts + │ ├── foo.ts + │ └── bar.ts + └── package.json +``` + +### bundle: false + +```ts title="rslib.config.ts" +export default defineConfig({ + lib: [ + { + format: 'cjs', + bundle: false, + }, + ], + source: { + entry: { + index: ['./src/**'], + }, + }, +}); +``` + +当 `bundle` 设置为 `false` 时,也称为 bundleless 模式,Rslib 只会将代码转换为多个文件。 + +```diff + . ++ ├── dist ++ │ ├── index.js ++ │ ├── foo.js ++ │ └── bar.js + ├── src + │ ├── index.ts + │ ├── foo.ts + │ └── bar.ts + └── package.json +``` diff --git a/website/docs/zh/config/lib/dts.mdx b/website/docs/zh/config/lib/dts.mdx index 21394ddcd..58d15d1fc 100644 --- a/website/docs/zh/config/lib/dts.mdx +++ b/website/docs/zh/config/lib/dts.mdx @@ -3,3 +3,190 @@ overviewHeaders: [2, 3] --- # lib.dts + +- **类型:** + +```ts +type Dts = + | { + bundle?: boolean; + distPath?: string; + build?: boolean; + abortOnError?: boolean; + autoExtension?: boolean; + } + | boolean; +``` + +- **默认值:** `undefined` + +配置 TypeScript 声明文件的生成。 + +## 布尔类型 + +DTS 生成是一个可选功能,你可以设置 `dts: true` 来启用 [bundleless 的 DTS](/guide/advanced/dts#bundleless-dts) 生成。 + +```ts title="rslib.config.ts" {5} +export default { + lib: [ + { + format: 'esm', + dts: true, + }, + ], +}; +``` + +如果你想要禁用 DTS 生成,可以设置 `dts: false` 或者不指定 `dts` 选项。 + +```ts title="rslib.config.ts" {5} +export default { + lib: [ + { + format: 'esm', + dts: false, + }, + ], +}; +``` + +## 对象类型 + +如果你想要自定义 DTS 的生成,可以将 `dts` 选项设置为一个对象。 + +### dts.bundle + +- **类型:** `boolean` +- **默认值:** `false` + +是否打包 DTS 文件。 + +#### 示例 + +如果你想要 [打包 DTS](/guide/advanced/dts#bundle-dts) 文件,你需要: + +1. 安装 [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) 作为开发依赖,它是用于打包 DTS 文件的底层工具。 + +import { PackageManagerTabs } from '@theme'; + + + +2. 将 `dts.bundle` 设置为 `true`。 + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + bundle: true, + }, + }, + ], +}; +``` + +::: note + +[@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) 只支持为单个入口打包 DTS。如果你想要为多个入口生成打包后的 DTS,你可以在 [lib](/config/lib/) 字段中添加额外的 lib 配置,将多个入口拆分为多个 lib 配置。 + +::: + +#### 处理第三方依赖 + +当我们打包 DTS 文件时,我们需要指定哪些第三方包的类型需要被打包,可以参考 [处理第三方依赖](/guide/advanced/third-party-deps) 文档了解更多关于 externals 相关的配置。 + +### dts.distPath + +- **类型:** `string` + +DTS 文件的输出目录。 + +#### 默认值 + +默认值按照以下优先级确定: + +1. 当前 lib 配置中的 `dts.distPath` 值。 +2. `tsconfig.json` 文件中的 `declarationDir` 值。 +3. 当前 lib 配置中的 [output.distPath.root](/config/rsbuild/output#outputdistpath) 值。 + +#### 示例 + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + distPath: './dist-types', + }, + }, + ], +}; +``` + +### dts.build + +- **类型:** `boolean` +- **默认值:** `false` + +决定是否在构建项目引用时生成 DTS 文件。这相当于在 `tsc` 命令中使用 `--build` 标志。更多详细信息请参考 [项目引用](https://www.typescriptlang.org/docs/handbook/project-references.html)。 + +::: note + +当启用此选项时,你必须在 `tsconfig.json` 中显式设置 `declarationDir` 或 `outDir` 以满足构建要求。 + +::: + +### dts.abortOnError + +- **类型:** `boolean` +- **默认值:** `true` + +当 DTS 生成过程中出现错误时,是否中止构建过程。 + +默认情况下,类型错误会导致构建失败。 + +当 `abortOnError` 设置为 `false` 时(如下所示),即使代码中存在类型问题,构建仍然会成功。 + +```ts title="rslib.config.ts" {5-7} +export default { + lib: [ + { + format: 'esm', + dts: { + abortOnError: false, + }, + }, + ], +}; +``` + +::: warning + +当禁用该配置时,无法保证类型文件会被正确生成。 + +::: + +### dts.autoExtension + +- **类型:** `boolean` +- **默认值:** `false` + +是否根据 [format](/config/lib/format) 选项自动设置 DTS 文件扩展名。 + +#### 默认扩展名 + +当 `dts.autoExtension` 为 `false` 时,DTS 文件扩展名默认为 `.d.ts`。 + +当 `dts.autoExtension` 设置为 `true` 时,DTS 文件扩展名将会是: + +- 当 `package.json` 中设置 `type: module` 时,`esm` 格式使用 `.d.ts`,`cjs` 格式使用 `.d.cts`。 + +- 当 `package.json` 中设置 `type: commonjs` 或没有 `type` 字段时,`cjs` 格式使用 `.d.ts`,`esm` 格式使用 `.d.mts`。 + +::: note + +这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑,但默认值不同,因为 DTS 文件扩展名可能会在不同的模块解析策略中造成一些问题。 + +::: diff --git a/website/docs/zh/config/lib/external-helpers.mdx b/website/docs/zh/config/lib/external-helpers.mdx index 0742c9ce4..e7f07cdfe 100644 --- a/website/docs/zh/config/lib/external-helpers.mdx +++ b/website/docs/zh/config/lib/external-helpers.mdx @@ -1 +1,110 @@ # lib.externalHelpers + +- **类型:** `boolean` +- **默认值:** `false` + +是否从 [@swc/helpers](https://www.npmjs.com/package/@swc/helpers) 导入 SWC 辅助函数而不是内联它们。 + +默认情况下,输出的 JavaScript 文件可能需要辅助函数来支持目标环境或输出格式,这些辅助函数会被内联到需要它们的文件中。 + +当 `externalHelpers` 设置为 `true` 时,输出的 JavaScript 将从外部模块 `@swc/helpers` 导入辅助函数。 + +::: note + +请确保在 `package.json` 的 `dependencies` 字段中声明并安装了 `@swc/helpers`。 + +::: + +## 示例 + +以下面的代码为例: + +```ts title="index.ts" +export default class FOO { + get bar() { + return; + } +} +``` + +当 `externalHelpers` 禁用时,输出的 JavaScript 将内联辅助函数。 + +```ts title="rslib.config.ts" {6} +export default { + lib: [ + // ... + syntax: 'es5' + ], + externalHelpers: false, +}; +``` + +以下是输出的 JavaScript 文件,高亮部分是内联的辅助函数: + +```js title="index.js" {1-18} +function _class_call_check(instance, Constructor) { + if (!(instance instanceof Constructor)) + throw new TypeError('Cannot call a class as a function'); +} +function _defineProperties(target, props) { + for (var i = 0; i < props.length; i++) { + var descriptor = props[i]; + descriptor.enumerable = descriptor.enumerable || false; + descriptor.configurable = true; + if ('value' in descriptor) descriptor.writable = true; + Object.defineProperty(target, descriptor.key, descriptor); + } +} +function _create_class(Constructor, protoProps, staticProps) { + if (protoProps) _defineProperties(Constructor.prototype, protoProps); + if (staticProps) _defineProperties(Constructor, staticProps); + return Constructor; +} +var src_FOO = /*#__PURE__*/ (function () { + 'use strict'; + function FOO() { + _class_call_check(this, FOO); + } + _create_class(FOO, [ + { + key: 'bar', + get: function () {}, + }, + ]); + return FOO; +})(); +export { src_FOO as default }; +``` + +当启用 `externalHelpers` 时,输出的 JavaScript 将从外部模块 `@swc/helpers` 导入辅助函数。 + +```ts title="rslib.config.ts" {6} +export default { + lib: [ + // ... + syntax: 'es5' + ], + externalHelpers: true, +}; +``` + +以下是输出的 JavaScript 文件,高亮部分是导入的辅助函数: + +```js title="index.js" {1-2} +import * as __WEBPACK_EXTERNAL_MODULE__swc_helpers_class_call_check__ from '@swc/helpers/_/_class_call_check'; +import * as __WEBPACK_EXTERNAL_MODULE__swc_helpers_create_class__ from '@swc/helpers/_/_create_class'; +var src_FOO = /*#__PURE__*/ (function () { + 'use strict'; + function FOO() { + (0, __WEBPACK_EXTERNAL_MODULE__swc_helpers_class_call_check__._)(this, FOO); + } + (0, __WEBPACK_EXTERNAL_MODULE__swc_helpers_create_class__._)(FOO, [ + { + key: 'bar', + get: function () {}, + }, + ]); + return FOO; +})(); +export { src_FOO as default }; +``` diff --git a/website/docs/zh/config/lib/footer.mdx b/website/docs/zh/config/lib/footer.mdx index 0b90ea4e2..21f5d9837 100644 --- a/website/docs/zh/config/lib/footer.mdx +++ b/website/docs/zh/config/lib/footer.mdx @@ -3,3 +3,77 @@ overviewHeaders: [2, 3] --- # lib.footer + +- **类型:** + +```ts +type Footer = { + js?: string; + css?: string; + dts?: string; +}; +``` + +- **默认值:** `{}` + +在每个 JavaScript、CSS 或 DTS 文件底部注入内容。 + +## 对象类型 + +### footer.js + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 JavaScript 输出文件底部注入内容。 + +### footer.css + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 CSS 输出文件底部注入内容。 + +### footer.dts + +- **类型:** `string` +- **默认值:** `undefined` + +在每个 DTS 输出文件底部注入内容。 + +## 注意事项 + +JavaScript 和 CSS 文件中的底部内容是基于 Rspack 的 [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) 实现的。你需要注意以下几点: + +- 默认启用了 `raw: true`,所以底部内容会作为原始字符串注入,而不是包裹在注释中。因此如果你想注入注释,需要自行添加 `/*` 和 `*/` 或其他注释语法。 +- `stage` 选项被设置在 JavaScript 和 CSS 文件优化之后的阶段,从而防止底部内容被优化掉。 + +## 自定义底部内容 + +如果以上默认设置无法满足你的需求,你可以通过 `tools.rspack.plugins` 自定义添加带有相应选项的 [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) 实例。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + // ... + tools: { + rspack: { + plugins: [ + new rspack.BannerPlugin({ + footer: true, + // ... options + }), + ], + }, + }, + }, + ], +}; +``` + +:::warning + +DTS 文件中的底部内容与 JavaScript 和 CSS 文件的处理方式不同。它是直接通过文件系统 API 写入的,所以设置 `BannerPlugin` 不会对其产生影响。 + +::: diff --git a/website/docs/zh/config/lib/format.mdx b/website/docs/zh/config/lib/format.mdx index a6428bf66..d605f1f8d 100644 --- a/website/docs/zh/config/lib/format.mdx +++ b/website/docs/zh/config/lib/format.mdx @@ -1 +1,13 @@ # lib.format + +- **类型:** `'esm' | 'cjs' | 'umd' | 'mf'` +- **默认值:** `undefined` +- **必填:** 是 + +指定生成的 JavaScript 产物的输出格式。 + +更多详情请参阅 [输出格式](/guide/basic/output-format) 和 [模块联邦](/guide/advanced/module-federation)。 + +::: note +`umd` 格式仅在 [bundle](/config/lib/bundle) 设置为 `true` 时有效。 +::: diff --git a/website/docs/zh/config/lib/id.mdx b/website/docs/zh/config/lib/id.mdx index 95550af66..e8c3125a1 100644 --- a/website/docs/zh/config/lib/id.mdx +++ b/website/docs/zh/config/lib/id.mdx @@ -1 +1,60 @@ # lib.id + +- **类型:** `string` +- **默认值:** `undefined` + +指定库的 ID。ID 用于标识库,在使用 CLI 的 `--lib` 标志构建特定库时,可以使用有意义的 `id` 进行构建。 + +:::tip + +Rslib 在底层使用了 Rsbuild 的 [environments](https://rsbuild.dev/guide/advanced/environments) 特性来在单个项目中构建多个库。`lib.id` 将被用作生成的 Rsbuild environment 的键名。 + +::: + +## 默认值 + +默认情况下,Rslib 会自动为每个库生成一个格式为 `${format}${index}` 的 ID。其中,`format` 是指当前库在 [format](/config/lib/format) 中指定的值,`index` 表示该库在所有相同格式的库中的序号。如果当前格式只有一个库,则 `index` 为空;否则,从 `0` 开始递增。 + +例如,`esm` 格式的库将从 `esm0` 开始,依次为 `esm1`、`esm2` 等。相比之下,`cjs` 和 `umd` 格式不包含 `index` 部分,因为每种格式只有一个库。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { format: 'esm' }, // id is `esm0` + { format: 'cjs' }, // id is `cjs` + { format: 'esm' }, // id is `esm1` + { format: 'umd' }, // id is `umd` + { format: 'esm' }, // id is `esm2` + ], +}; +``` + +## 自定义 ID + +你可以通过在库配置中设置 `id` 字段来指定一个可读性更强或更有意义的库 ID。用户指定的 ID 将优先使用,而其余的将继续使用默认生成的 ID。 + +例如,`my-lib-a`、`my-lib-b` 和 `my-lib-c` 将作为指定库的 ID,而其余的库将使用生成的默认 ID。 + +{/* prettier-ignore-start */} +```ts title="rslib.config.ts" +export default { + lib: [ + { format: 'esm', id: 'my-lib-a' }, // ID is `my-lib-a` + { format: 'cjs', id: 'my-lib-b' }, // ID is `my-lib-b` + { format: 'esm' }, // ID is `esm0` + { format: 'umd', id: 'my-lib-c' }, // ID is `my-lib-c` + { format: 'esm' }, // ID is `esm1` + ], +}; +``` +{/* prettier-ignore-end */} + +然后你可以通过运行以下命令来单独构建 `my-lib-a` 和 `my-lib-b`: + +```bash +npx rslib build --lib my-lib-a --lib my-lib-b +``` + +:::note +每个库的 ID 必须是唯一的,否则会导致错误。 +::: diff --git a/website/docs/zh/config/lib/redirect.mdx b/website/docs/zh/config/lib/redirect.mdx index 3f144c2e4..668f7dacd 100644 --- a/website/docs/zh/config/lib/redirect.mdx +++ b/website/docs/zh/config/lib/redirect.mdx @@ -1 +1,50 @@ # lib.redirect + +- **类型:** + +```ts +type Redirect = { + style?: boolean; +}; +``` + +- **默认值:** + +```ts +const defaultRedirect = { + style: true, +}; +``` + +配置导入路径的重定向。 + +当 `bundle: false` 时,会对导入路径进行重定向,以确保它指向正确的输出。 + +:::note + +由于 bundleless 模式仍在开发中,未来会引入更多重定向配置。 + +::: + +如果你不需要这些重定向,可以关闭它,这样导入路径将保持不变。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + redirect: { + style: false, // 关闭样式文件的重定向 + }, + }, + ], +}; +``` + +## redirect.style + +- **类型:** `boolean` +- **默认值:** `true` + +是否重定向样式文件的导入路径。例如: + +- `import './index.less'` 将被重写为 `import './index.css'` diff --git a/website/docs/zh/config/lib/shims.mdx b/website/docs/zh/config/lib/shims.mdx index 66bcb9301..85acb6cd2 100644 --- a/website/docs/zh/config/lib/shims.mdx +++ b/website/docs/zh/config/lib/shims.mdx @@ -3,3 +3,180 @@ overviewHeaders: [2, 3] --- # lib.shims + +- **类型:** + +```ts +type Shims = { + cjs?: { + 'import.meta.url'?: boolean; + }; + esm?: { + __filename?: boolean; + __dirname?: boolean; + require?: boolean; + }; +}; +``` + +- **默认值:** + +```js +const defaultShims = { + cjs: { + 'import.meta.url': true, + }, + esm: { + __filename: false, + __dirname: false, + require: false, + }, +}; +``` + +配置 CommonJS 和 ESM 输出的 [shims(垫片)](https://developer.mozilla.org/zh-CN/docs/Glossary/Shim)。 + +## shims.cjs + +将字段设置为 `true` 以启用对应的 CommonJS 输出 shims。 + +### shims.cjs['import.meta.url'] + +- **默认值:** `true` + +选项: + +- `true`:当 [format](/config/lib/format) 为 `cjs` 时,源代码中的 `import.meta.url` 将被替换为当前模块的 URL。 + + 例如,给定以下源代码: + + ```js + import { readFileSync } from 'fs'; + const buffer = readFileSync(new URL('./data.proto', import.meta.url)); + ``` + + 将被转换为以下 CJS 输出代码: + + ```js + const { readFileSync } = require('fs'); + const buffer = readFileSync( + new URL( + './data.proto', + /*#__PURE__*/ (function () { + return typeof document === 'undefined' + ? new (module.require('url'.replace('', '')).URL)( + 'file:' + __filename, + ).href + : (document.currentScript && document.currentScript.src) || + new URL('main.js', document.baseURI).href; + })(), + ), + ); + ``` + +- `false`:`import.meta.url` 将保持原样,这将会导致运行时错误。 + +## shims.esm + +将字段设置为 `true` 以启用对应的 ESM 输出 shims。 + +### shims.esm.\_\_filename + +是否在 ESM 输出中为 CommonJS 的全局 `__filename` 注入 shims。 + +- **默认值:** `false` + +选项: + +- `true`:当 [format](/config/lib/format) 为 `esm` 时,源代码中的 `__filename` 将被替换为当前模块的文件名。 + + 例如,给定以下源代码: + + ```js + console.log(__filename); + ``` + + ESM 输出将被转换为: + + ```js + import { fileURLToPath as __webpack_fileURLToPath__ } from 'url'; + import { dirname as __webpack_dirname__ } from 'path'; + var src_dirname = __webpack_dirname__( + __webpack_fileURLToPath__(import.meta.url), + ); + var src_filename = __webpack_fileURLToPath__(import.meta.url); + console.log(src_filename); + ``` + +- `false`:`__filename` 将保持原样,这将会导致运行时错误。 + +### shims.esm.\_\_dirname + +是否在 ESM 输出中为 CommonJS 的全局 `__dirname` 注入 shims。 + +- **默认值:** `false` + +选项: + +- `true`:当 [format](/config/lib/format) 为 `esm` 时,源代码中的 `__dirname` 将被替换为当前模块的目录名。 + + 例如,给定以下源代码: + + ```js + console.log(__dirname); + ``` + + ESM 输出将被转换为: + + ```js + import { fileURLToPath as __webpack_fileURLToPath__ } from 'url'; + import { dirname as __webpack_dirname__ } from 'path'; + var src_dirname = __webpack_dirname__( + __webpack_fileURLToPath__(import.meta.url), + ); + console.log(src_dirname); + ``` + +- `false`:`__dirname` 将保持原样,这将会导致运行时错误。 + +### shims.esm.require + +是否在 ESM 输出中为 CommonJS 的全局 `require` 注入 shims。 + +- **默认值:** `false` + +选项: + +- `true`:当 [format](/config/lib/format) 为 `esm` 时,在输出的开头将会创建一个由 `createRequire` 生成的 `require`,可以在源代码中像 CommonJS 的全局 `require` 一样使用。 + + 例如,给定以下源代码: + + ```js + const someModule = require('./someModule'); + + // dynamic require + const dynamicRequiredModule = require(SOME_VALUE_IN_RUNTIME); + // require.resolve + const someModulePath = require.resolve('./someModule'); + // use require as a expression + const lazyFn = (module, requireFn) => {}; + lazyFn('./other.js', require); + ``` + + ESM 输出将被转换为: + + ```js + import __rslib_shim_module__ from 'module'; + const require = /*#__PURE__*/ __rslib_shim_module__.createRequire( + import.meta.url, + ); + // dynamic require + require(SOME_VALUE_IN_RUNTIME); + // require.resolve + require.resolve('./someModule'); + // use require as a expression + const lazyFn = (module, requireFn) => {}; + lazyFn('./other.js', require); + ``` + +- `false`: `require` 将保持原样,这将会导致运行时错误。 diff --git a/website/docs/zh/config/lib/syntax.mdx b/website/docs/zh/config/lib/syntax.mdx index 89cf6a15a..ec0a90970 100644 --- a/website/docs/zh/config/lib/syntax.mdx +++ b/website/docs/zh/config/lib/syntax.mdx @@ -1 +1,69 @@ # lib.syntax + +- **类型:** + +```ts +type EcmaScriptVersion = + | 'es5' + | 'es6' + | 'es2015' + | 'es2016' + | 'es2017' + | 'es2018' + | 'es2019' + | 'es2020' + | 'es2021' + | 'es2022' + | 'es2023' + | 'es2024' + | 'esnext'; + +type Syntax = EcmaScriptVersion | string[]; +``` + +- **默认值:** `'esnext'` + +配置 JavaScript 和 CSS 将被降级的语法版本。 + +参见 [产物兼容性 - 语法降级](/guide/advanced/output-compatibility) 了解更多详情。 + +## 设置 ECMAScript 版本 + +你可以直接设置 ECMAScript 版本,例如 `es2015`、`es2022` 等。 + +```ts title="rslib.config.ts" +export default { + lib: [ + // ... + ], + syntax: 'es2015', +}; +``` + +## 设置 Browserslist 查询 + +你也可以设置 [Browserslist 查询语句](https://browsersl.ist/),例如 `last 2 versions`、`> 1%`、`node >= 16`、`chrome >= 80` 等。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + syntax: ['last 2 versions', '> 1%'], + }, + ], +}; +``` + +## 混合使用 ECMAScript 版本和 Browserslist 查询 + +你也可以混合使用 ECMAScript 版本和 Browserslist 查询语句,例如 `es2015` 和 `node 20`。Rslib 会将 ECMAScript 版本转换为 Browserslist 查询语句,然后将它们合并在一起。 + +```ts title="rslib.config.ts" +export default { + lib: [ + { + syntax: ['es2015', 'node 20'], + }, + ], +}; +``` diff --git a/website/docs/zh/config/lib/umd-name.mdx b/website/docs/zh/config/lib/umd-name.mdx index 0ef9a503e..f5cc3eaf3 100644 --- a/website/docs/zh/config/lib/umd-name.mdx +++ b/website/docs/zh/config/lib/umd-name.mdx @@ -1 +1,27 @@ # lib.umdName + +- **类型:** `string` +- **默认值:** `undefined` + +[UMD](/guide/basic/output-format#umd) 包的导出名称。 + +:::tip + +UMD 包的模块名称不能与全局变量名称冲突。 + +::: + +## 示例 + +UMD 包将会挂载到 `global.MyLibrary`。 + +```ts title="rslib.config.ts" {5} +export default { + lib: [ + { + format: 'umd', + umdName: 'MyLibrary', + }, + ], +}; +```