docs: add redirect/syntax/externalHelpers/banner/footer/umdName lib config (#383)

Timeless0911 · web-flow · commit ce4dea9c12b7 · 2024-11-08T17:34:58.000+08:00
diff --git a/packages/core/src/types/config/index.ts b/packages/core/src/types/config/index.ts
@@ -88,17 +88,18 @@ export interface LibConfig extends RsbuildConfig {
    */
   autoExtension?: boolean;
   /**
-   * Whether to automatically externalize dependencies and do not bundle them.
+   * Whether to automatically externalize dependencies of different dependency types and do not bundle them.
    * @default true
    */
   autoExternal?: AutoExternal;
   /**
-   * Configure the redirect of the import paths.
+   * Configure the redirect of the import paths, applicable when `bundle: false`.
    * @default {}
    */
   redirect?: Redirect;
   /**
-   * Support esX and browserslist query
+   * Configure the syntax to which JavaScript and CSS will be downgraded.
+   * Support ECMAScript version and browserslist query.
    * @default 'esnext'
    */
   syntax?: Syntax;
diff --git a/website/docs/en/config/lib/auto-external.mdx b/website/docs/en/config/lib/auto-external.mdx
@@ -15,30 +15,32 @@ type AutoExternal =
 
 - **Default:** `true`
 
-Whether to automatically externalize dependencies and do not bundle them.
+Whether to automatically externalize dependencies of different dependency types and do not bundle them.
 
-## autoExternal.dependencies
+## Object Type
+
+### autoExternal.dependencies
 
 - **Type:** `boolean`
 - **Default:** `true`
 
 Whether to externalize dependencies of type `dependencies`.
 
-## autoExternal.optionalDependencies
+### autoExternal.optionalDependencies
 
 - **Type:** `boolean`
 - **Default:** `true`
 
 Whether to externalize dependencies of type `optionalDependencies`.
 
-## autoExternal.peerDependencies
+### autoExternal.peerDependencies
 
 - **Type:** `boolean`
 - **Default:** `true`
 
 Whether to externalize dependencies of type `peerDependencies`.
 
-## autoExternal.devDependencies
+### autoExternal.devDependencies
 
 - **Type:** `boolean`
 - **Default:** `false`
@@ -57,7 +59,7 @@ And the following dependency types will be **bundled**:
 
 - `devDependencies`
 
-It is equivalent to the following configuration:
+This configuration is equivalent to the following object type:
 
 ```ts
 export default {
diff --git a/website/docs/en/config/lib/banner.mdx b/website/docs/en/config/lib/banner.mdx
@@ -13,3 +13,62 @@ type Banner = {
 - **Default:** `{}`
 
 Inject content into the top of each JS, CSS or DTS file.
+
+## Object Type
+
+### banner.js
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the top of each JS file.
+
+### banner.css
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the top of each CSS file.
+
+### banner.dts
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the top of each DTS 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:
+
+- `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.
+
+## Customize Banner Content
+
+If the above default settings cannot meet your requirements, you can customize the banner content through `tools.rspack.plugins` to add a [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) instance with the corresponding options.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      // ...
+      tools: {
+        rspack: {
+          plugins: [
+            new rspack.BannerPlugin({
+              // ... options
+            }),
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+:::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.
+
+:::
diff --git a/website/docs/en/config/lib/external-helpers.mdx b/website/docs/en/config/lib/external-helpers.mdx
@@ -3,4 +3,108 @@
 - **Type:** `boolean`
 - **Default:** `false`
 
-Whether to import SWC helper functions from `@swc/helpers` instead of inlining them.
+Whether to import SWC helper functions from [@swc/helpers](https://www.npmjs.com/package/@swc/helpers) instead of inlining them.
+
+By default, the output JavaScript file may depend on helper functions to support the target environment or output format, and these helper functions will be inlined in the file that requires it.
+
+When `externalHelpers` set to `true`, the output JavaScript will import helper functions from the external module `@swc/helpers`.
+
+::: note
+
+Make sure to declare the `@swc/helpers` in `dependencies` field of `package.json`.
+
+:::
+
+## Example
+
+Take the following code as an example:
+
+```ts title="index.ts"
+export default class FOO {
+  get bar() {
+    return;
+  }
+}
+```
+
+When `externalHelpers` is disabled, the output JavaScript will inline helper functions.
+
+```ts title="rslib.config.ts" {6}
+export default {
+  lib: [
+    // ...
+    syntax: 'es5'
+  ],
+  externalHelpers: false,
+};
+```
+
+Below is the output JavaScript file:
+
+```js title="index.js"
+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 };
+```
+
+When `externalHelpers` is enabled, the output JavaScript will import helper functions from the external module `@swc/helpers`.
+
+```ts title="rslib.config.ts" {6}
+export default {
+  lib: [
+    // ...
+    syntax: 'es5'
+  ],
+  externalHelpers: true,
+};
+```
+
+Below is the output JavaScript file:
+
+```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/en/config/lib/footer.mdx b/website/docs/en/config/lib/footer.mdx
@@ -13,3 +13,63 @@ type Footer = {
 - **Default:** `{}`
 
 Inject content into the bottom of each JS, CSS or DTS file.
+
+## Object Type
+
+### footer.js
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the bottom of each JS file.
+
+### footer.css
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the bottom of each CSS file.
+
+### footer.dts
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Inject content into the bottom of each DTS 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:
+
+- `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.
+
+## Customize Footer Content
+
+If the above default settings cannot meet your requirements, you can customize the footer content through `tools.rspack.plugins` to add a [BannerPlugin](https://rspack.dev/plugins/webpack/banner-plugin) instance with the corresponding options.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      // ...
+      tools: {
+        rspack: {
+          plugins: [
+            new rspack.BannerPlugin({
+              footer: true,
+              // ... options
+            }),
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+:::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.
+
+:::
diff --git a/website/docs/en/config/lib/redirect.mdx b/website/docs/en/config/lib/redirect.mdx
@@ -8,6 +8,42 @@ type Redirect = {
 };
 ```
 
-- **Default:** `{}`
+- **Default:**
+
+```ts
+const defaultRedirect = {
+  style: true,
+};
+```
 
 Configure the redirect of the import paths.
+
+When `bundle: false`, the import path is redirected to ensure that it points to the correct output.
+
+:::note
+
+As bundleless mode is still under development, additional redirect configurations will be introduced in the future.
+
+:::
+
+If you don't need these redirects, you can turn it off, and its import path will not be changed.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    // ..
+  ],
+  redirect: {
+    style: false, // Turn off the redirect of the style file
+  },
+};
+```
+
+## redirect.style
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to redirect the import path of the style file. For example:
+
+- `import './index.less'` will be rewritten to `import './index.css'`
diff --git a/website/docs/en/config/lib/shims.mdx b/website/docs/en/config/lib/shims.mdx
@@ -34,7 +34,7 @@ const defaultShims = {
 };
 ```
 
-Used to configure the shims for CommonJS and ESM output.
+Configure the shims for CommonJS and ESM output.
 
 ## shims.cjs
 
@@ -46,7 +46,7 @@ Set the fields to `true` to enable the corresponding shims for CommonJS output.
 
 Options:
 
-- `true`: when `format` is `cjs`, the `import.meta.url` in source code will be replaced with the URL of the current module.
+- `true`: when [format](/config/lib/format) is `cjs`, the `import.meta.url` in source code will be replaced with the URL of the current module.
 
   For example, given the following source code:
 
@@ -88,7 +88,7 @@ Whether to shim the global `__filename` of CommonJS in ESM output.
 
 Options:
 
-- `true`: when `format` is `esm`, the `__filename` in source code will be replaced with the filename of the current module.
+- `true`: when [format](/config/lib/format) is `esm`, the `__filename` in source code will be replaced with the filename of the current module.
 
   For example, given the following source code:
 
@@ -118,7 +118,7 @@ Whether to shim the global `__dirname` of CommonJS in ESM output.
 
 Options:
 
-- `true`: when `format` is `esm`, the `__dirname` in source code will be replaced with the directory name of the current module.
+- `true`: when [format](/config/lib/format) is `esm`, the `__dirname` in source code will be replaced with the directory name of the current module.
 
   For example, given the following source code:
 
@@ -147,7 +147,7 @@ Whether to shim the global `require` of CommonJS in ESM output.
 
 Options:
 
-- `true`: when `format` is `esm`, there will be a `require` that created by `createRequire` at the beginning of the output which can be accessed in source code like the global `require` like CommonJS.
+- `true`: when [format](/config/lib/format) is `esm`, there will be a `require` that created by `createRequire` at the beginning of the output which can be accessed in source code like the global `require` like CommonJS.
 
   For example, given the following source code:
 
diff --git a/website/docs/en/config/lib/syntax.mdx b/website/docs/en/config/lib/syntax.mdx
diff --git a/website/docs/en/config/lib/umd-name.mdx b/website/docs/en/config/lib/umd-name.mdx
