docs: add redirect/syntax/externalHelpers/banner/footer/umdName lib config

Author: Timeless0911

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;

website/docs/en/config/lib/auto-external.mdx

@@ -15,35 +15,7 @@ type AutoExternal =
 
 - **Default:** `true`
 
-Whether to automatically externalize dependencies and do not bundle them.
-
-## autoExternal.dependencies
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-Whether to externalize dependencies of type `dependencies`.
-
-## autoExternal.optionalDependencies
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-Whether to externalize dependencies of type `optionalDependencies`.
-
-## autoExternal.peerDependencies
-
-- **Type:** `boolean`
-- **Default:** `true`
-
-Whether to externalize dependencies of type `peerDependencies`.
-
-## autoExternal.devDependencies
-
-- **Type:** `boolean`
-- **Default:** `false`
-
-Whether to bundle dependencies of type `devDependencies`.
+Whether to automatically externalize dependencies of different dependency types and do not bundle them.
 
 ## Default Value
 

website/docs/en/config/lib/banner.mdx

@@ -13,3 +13,39 @@ type Banner = {
 - **Default:** `{}`
 
 Inject content into the top of each JS, CSS or 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.
+
+:::

website/docs/en/config/lib/external-helpers.mdx

@@ -4,3 +4,107 @@
 - **Default:** `false`
 
 Whether to import SWC helper functions from `@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`.
+
+::: tip
+
+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"
+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 };
+```

website/docs/en/config/lib/footer.mdx

@@ -13,3 +13,40 @@ type Footer = {
 - **Default:** `{}`
 
 Inject content into the bottom of each JS, CSS or 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.
+
+:::

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'`

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:
 

website/docs/en/config/lib/syntax.mdx

@@ -22,3 +22,46 @@ type Syntax = EcmaScriptVersion | string[];
 ```
 
 - **Default:** `'esnext'`
+
+Configure the syntax to which JavaScript and CSS will be downgraded.
+
+See [Output Compatibility - Syntax Downgrade](/guide/advanced/output-compatibility) for more details.
+
+## Set ECMAScript Version
+
+You can set the ECMAScript version directly, such as `es2015`, `es2022`, etc.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    // ...
+  ],
+  syntax: 'es2015',
+};
+```
+
+## Set Browserslist Query
+
+You can also set the Browserslist query, such as `last 2 versions`, `> 1%`, `node >= 16`, `chrome >= 80`, etc.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    // ...
+  ],
+  syntax: ['last 2 versions', '> 1%'],
+};
+```
+
+## 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.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    // ...
+  ],
+  syntax: ['es2015', 'node 20'],
+};
+```