docs: add lib.bundle/format/autoExtension doc

packages/core/src/types/config/index.ts

@@ -72,18 +72,18 @@ export type Redirect = {
 };
 
 export interface LibConfig extends RsbuildConfig {
-  /**
-   * Whether to bundle the library.
-   * @default true
-   */
-  bundle?: boolean;
   /**
    * Output format for the generated JavaScript files.
    * @default undefined
    */
   format?: Format;
   /**
-   * Whether to automatically set the file extension based on the `format` option in the JS and DTS output files.
+   * Whether to bundle the library.
+   * @default true
+   */
+  bundle?: boolean;
+  /**
+   * Whether to automatically set the file extension based on the `format` option in the JavaScript output files.
    * @default true
    */
   autoExtension?: boolean;

website/docs/en/config/_meta.json

@@ -7,11 +7,11 @@
   {
     "type": "dir",
     "name": "lib",
-    "label": "Lib"
+    "label": "Lib Configurations"
   },
   {
     "type": "dir",
     "name": "rsbuild",
-    "label": "Rsbuild Config"
+    "label": "Rsbuild Configurations"
   }
 ]

website/docs/en/config/lib.mdx

@@ -1 +1,30 @@
-# Lib
+# Lib Configurations
+
+- **Type:**
+
+```ts
+interface LibConfig extends RsbuildConfig {
+  format?: Format;
+  bundle?: boolean;
+  autoExtension?: boolean;
+  autoExternal?: AutoExternal;
+  redirect?: Redirect;
+  syntax?: Syntax;
+  externalHelpers?: boolean;
+  banner?: BannerAndFooter;
+  footer?: BannerAndFooter;
+  shims?: Shims;
+  dts?: Dts;
+  umdName?: string;
+}
+
+interface RslibConfig extends RsbuildConfig {
+  lib: LibConfig[];
+}
+```
+
+- **Default:** `undefined`
+
+- **Required:** `true`
+
+The `lib` configuration is an array of objects, each representing a distinct set of configurations. These include all Rsbuild configurations as well as Rslib-specific configurations, designed to generate different outputs.

website/docs/en/config/lib/_meta.json

@@ -1,6 +1,6 @@
 [
-  "bundle",
   "format",
+  "bundle",
   "auto-extension",
   "auto-external",
   "redirect",

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

@@ -3,4 +3,50 @@
 - **Type:** `boolean`
 - **Default:** `true`
 
-Whether to automatically set the file extension based on the `format` option in the JS and DTS output files.
+Whether to automatically set the file extension based on the [`format`](/config/lib/format) option in the JavaScript output files.
+
+## Default Extension
+
+By default that when `autoExtension` is set to `true`, the file extension will be:
+
+- `.js` with `esm` format and `.cjs` with `cjs` format when `type: module` in `package.json`.
+
+- `.js` with `cjs` format and `.mjs` with `esm` format when `type: commonjs` or no `type` field in `package.json`.
+
+:::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.
+
+For example, if `foo` is a folder, you need to rewrite `import * from './foo'` to `import * from './foo/index'`.
+
+:::
+
+When `autoExtension` is set to `false`, the file extension will be default to `.js`.
+
+## Customize Extension
+
+You can set `autoExtension` to `false` and use [output.filename](https://rsbuild.dev/config/output/filename) to customize the JavaScript output files.
+
+```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',
+        },
+      },
+    },
+  ],
+});
+```

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

@@ -3,4 +3,146 @@
 - **Type:** `boolean`
 - **Default:** `true`
 
-Whether to bundle the library.
+Specify whether to bundle the library, which is known as bundle mode when `bundle` is set to `true`, and bundleless mode when set to `false`.
+
+See [bundle / bundleless](/guide/basic/output-structure#bundle--bundleless) for more details.
+
+::: warning
+
+The bundleless mode is not fully supported yet, and some features like [assets](/guide/advanced/assets) may not work properly.
+
+:::
+
+## Set Entry
+
+We should specify the entry file for the build.
+
+### bundle: true
+
+When `bundle` is set to `true`, the entry should be set to the entry file. The default entry is `src/index.(ts|js|tsx|jsx|mjs|cjs)`. You should make sure that the entry file exists, or customize entry through the [source.entry](https://rsbuild.dev/config/source/entry) configuration.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      format: 'cjs',
+      bundle: true,
+    },
+  ],
+  source: {
+    entry: {
+      index: './foo/index.ts',
+    },
+  },
+};
+```
+
+### bundle: false
+
+When `bundle` is set to `false`, the entry should be set a [glob pattern](https://github.com/micromatch/picomatch#globbing-features) to include all the files.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      format: 'cjs',
+      bundle: false,
+    },
+  ],
+  source: {
+    entry: {
+      index: './src/**',
+    },
+  },
+};
+```
+
+You can also use with an exclamation mark to exclude some files.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      format: 'cjs',
+      bundle: false,
+    },
+  ],
+  source: {
+    entry: {
+      index: ['./src/**', '!**/foo.*'],
+    },
+  },
+};
+```
+
+## Example
+
+For below file structure of source code:
+
+```
+.
+├── src
+│   ├── index.ts
+│   ├── foo.ts
+│   └── bar.ts
+└── package.json
+```
+
+### bundle: true
+
+```ts title="rslib.config.ts"
+export default defineConfig({
+  lib: [
+    {
+      format: 'cjs',
+      bundle: true,
+    },
+  ],
+});
+```
+
+When `bundle` is set to `true`, as known as bundle mode, Rslib will bundle the library into a single file.
+
+```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/**'],
+    },
+  },
+});
+```
+
+When `bundle` is set to `false`, as known as bundleless mode, Rslib will only transform the code into multiple files.
+
+```diff
+  .
++ ├── dist
++ │   ├── index.js
++ │   ├── foo.js
++ │   └── bar.js
+  ├── src
+  │   ├── index.ts
+  │   ├── foo.ts
+  │   └── bar.ts
+  └── package.json
+```

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

@@ -1,6 +1,17 @@
 # lib.format
 
-- **Type:** `string`
+- **Type:** `'esm' | 'cjs' | 'umd' | 'mf'`
+
 - **Default:** `undefined`
 
-Output format for the generated JavaScript files.
+- **Required**: true
+
+Specify the output format for the generated JavaScript files.
+
+See [Output Format](/guide/basic/output-format) and [Module Federation](/guide/advanced/module-federation) for more details.
+
+::: note
+
+The `umd` format only works when [bundle](/config/lib/bundle) is set to `true`.
+
+:::

website/docs/en/config/rsbuild.mdx

@@ -1 +1 @@
-# Rsbuild Configuration
+# Rsbuild Configurations

website/docs/en/guide/basic/configure-rslib.mdx

@@ -82,9 +82,9 @@ export default {
 
 The configuration file exports a default object that includes a `lib` array and shared Rsbuild configuration options. You can find detailed descriptions of all configs on the [Configure Overview](/config/) page.
 
-- **[Lib configurations](/config/lib) (at least one object is required)**: The `lib` array contains multiple objects, each representing a set of independent configurations that will generate different outputs. Each object within the `lib` array can specify unique configurations, which is a superset of Rsbuild
+- **[Lib Configurations](/config/lib) (at least one object is required)**: The `lib` array contains multiple objects, each representing a set of independent configurations that will generate different outputs. Each object within the `lib` array can specify unique configurations, which is a superset of Rsbuild
   configurations along with Rslib's specific configurations.
-- **Shared [Rsbuild configurations](/config/rsbuild) (optional)**: Outside the `lib` array, there are shared Rsbuild configuration options that will be deep merged with independent Rsbuild configuration of each `lib` configuration object.
+- **Shared [Rsbuild Configurations](/config/rsbuild) (optional)**: Outside the `lib` array, there are shared Rsbuild configuration options that will be deep merged with independent Rsbuild configuration of each `lib` configuration object.
 
 Rslib generates corresponding Rsbuild [environments](https://rsbuild.dev/guide/advanced/environments) configurations based on the multiple build configurations of different output formats. You can view the final generated configurations through the [configuration debug](#configuration-debug) documentation.
 

website/docs/en/guide/basic/output-format.mdx

@@ -83,16 +83,16 @@ A detailed answer from StackOverflow: [What is the Universal Module Definition (
 
 ### How to build a UMD library?
 
-- Set the `output.format` to `umd` in the Rslib configuration file.
-- If the library need to be exported with a name, set `output.umdName` to the name of the UMD library.
+- Set the `lib.format` to `umd` in the Rslib configuration file.
+- If the library need to be exported with a name, set `lib.umdName` to the name of the UMD library.
 - Use `output.externals` to specify the external dependencies that the UMD library depends on, `lib.autoExtension` is enabled by default for UMD.
 
 ### Examples
 
 The following Rslib config is an example to build a UMD library.
 
-- `output.format: 'umd'`: instruct Rslib to build in UMD format.
-- `output.umdName: 'RslibUmdExample'`: set the export name of the UMD library.
+- `lib.format: 'umd'`: instruct Rslib to build in UMD format.
+- `lib.umdName: 'RslibUmdExample'`: set the export name of the UMD library.
 - `output.externals.react: 'React'`: specify the external dependency `react` could be accessed by `window.React`.
 - `runtime: 'classic'`: use the classic runtime of React to support applications that using React version under 18.