feat(dts): support override bundledPackages (#1025)

Author: Timeless0911

packages/core/src/types/config.ts

@@ -54,7 +54,16 @@ export type Dts =
        * @defaultValue `false`
        * @see {@link https://rslib.rs/config/lib/dts#dtsbundle}
        */
-      bundle?: boolean;
+      bundle?:
+        | boolean
+        | {
+            /**
+             * Specifies the dependencies whose declaration files should be bundled.
+             * @defaultValue {@link https://rslib.rs/config/lib/dts#dtsbundlebundledpackages}
+             * @see {@link https://rslib.rs/config/lib/dts#dtsbundlebundledpackages}
+             */
+            bundledPackages?: string[];
+          };
       /**
        * The output directory of declaration files.
        * @defaultValue {@link https://rslib.rs/config/lib/dts#default-value}

packages/plugin-dts/README.md

@@ -54,6 +54,33 @@ pluginDts({
 });
 ```
 
+#### bundle.bundledPackages
+
+- **Type:** `string[]`
+
+Specifies the dependencies whose declaration files should be bundled. This configuration is passed to the [bundledPackages](https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages) option of `@microsoft/api-extractor`.
+
+By default, `rsbuild-plugin-dts` determines externalized dependencies based on the following configurations.
+
+- [autoExternal](#autoexternal) configuration
+- [output.externals](https://rsbuild.rs/config/output/externals) configuration
+
+Direct dependencies (declared in `package.json`) that are not externalized will be automatically added to `bundledPackages`, and their declaration files will be bundled into the final output.
+
+When the default behavior does not meet the requirements, you can explicitly specify the dependencies whose declaration files need to be bundled through `bundle.bundledPackages`. After setting this configuration, the above default behavior will be completely overwritten.
+
+This is typically used for bundling transitive dependencies (dependencies of direct dependencies). For example, if the project directly depends on `foo`, and `foo` depends on `bar`, you can bundle both `foo` and `bar`'s declaration files as follows:
+
+```js
+pluginDts({
+  bundle: {
+    bundledPackages: ['foo', 'bar'],
+  },
+});
+```
+
+> `bundledPackages` can be specified with the [minimatch](https://www.npmjs.com/package/minimatch) syntax, but will only match the declared direct dependencies in `package.json`.
+
 ### distPath
 
 - **Type:** `string`

packages/plugin-dts/src/dts.ts

@@ -19,11 +19,16 @@ const isObject = (obj: unknown): obj is Record<string, any> =>
 
 // use !externals
 export const calcBundledPackages = (options: {
-  autoExternal: DtsGenOptions['autoExternal'];
   cwd: string;
+  autoExternal: DtsGenOptions['autoExternal'];
   userExternals?: DtsGenOptions['userExternals'];
+  overrideBundledPackages?: string[];
 }): string[] => {
-  const { autoExternal, cwd, userExternals } = options;
+  const { cwd, autoExternal, userExternals, overrideBundledPackages } = options;
+
+  if (overrideBundledPackages) {
+    return overrideBundledPackages;
+  }
 
   let pkgJson: {
     dependencies?: Record<string, string>;
@@ -119,6 +124,7 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
     dtsExtension = '.d.ts',
     autoExternal = true,
     userExternals,
+    apiExtractorOptions,
     banner,
     footer,
     redirect = {
@@ -213,9 +219,10 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
         banner,
         footer,
         bundledPackages: calcBundledPackages({
-          autoExternal,
           cwd,
+          autoExternal,
           userExternals,
+          overrideBundledPackages: apiExtractorOptions?.bundledPackages,
         }),
       });
     }

packages/plugin-dts/src/index.ts

@@ -22,8 +22,12 @@ export type DtsRedirect = {
   extension?: boolean;
 };
 
+export type ApiExtractorOptions = {
+  bundledPackages?: string[];
+};
+
 export type PluginDtsOptions = {
-  bundle?: boolean;
+  bundle?: boolean | ApiExtractorOptions;
   distPath?: string;
   build?: boolean;
   abortOnError?: boolean;
@@ -46,7 +50,8 @@ export type DtsEntry = {
   path?: string;
 };
 
-export type DtsGenOptions = PluginDtsOptions & {
+export type DtsGenOptions = Omit<PluginDtsOptions, 'bundle'> & {
+  bundle: boolean;
   name: string;
   cwd: string;
   isWatch: boolean;
@@ -56,6 +61,7 @@ export type DtsGenOptions = PluginDtsOptions & {
   tsconfigPath: string;
   tsConfigResult: ts.ParsedCommandLine;
   userExternals?: NonNullable<RsbuildConfig['output']>['externals'];
+  apiExtractorOptions?: ApiExtractorOptions;
 };
 
 interface TaskResult {
@@ -71,7 +77,15 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
   name: PLUGIN_DTS_NAME,
 
   setup(api) {
-    options.bundle = options.bundle ?? false;
+    let apiExtractorOptions = {};
+
+    if (options.bundle && typeof options.bundle === 'object') {
+      apiExtractorOptions = {
+        ...options.bundle,
+      };
+    }
+
+    const bundle = !!options.bundle;
     options.abortOnError = options.abortOnError ?? true;
     options.build = options.build ?? false;
     options.redirect = options.redirect ?? {};
@@ -93,10 +107,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
         // @microsoft/api-extractor only support single entry to bundle declaration files
         // see https://github.com/microsoft/rushstack/issues/1596#issuecomment-546790721
         // we support multiple entries by calling api-extractor multiple times
-        const dtsEntry = processSourceEntry(
-          options.bundle!,
-          config.source?.entry,
-        );
+        const dtsEntry = processSourceEntry(bundle, config.source?.entry);
 
         const cwd = api.context.rootPath;
         const tsconfigPath = ts.findConfigFile(
@@ -132,7 +143,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
         }
 
         // clean .rslib temp folder
-        if (options.bundle) {
+        if (bundle) {
           await clearTempDeclarationDir(cwd);
         }
 
@@ -150,9 +161,11 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
 
         const dtsGenOptions: DtsGenOptions = {
           ...options,
+          bundle,
           dtsEntry,
           dtsEmitPath,
           userExternals: config.output.externals,
+          apiExtractorOptions,
           tsconfigPath,
           tsConfigResult,
           name: environment.name,

packages/plugin-dts/tests/external.test.ts

@@ -105,4 +105,18 @@ describe('should calcBundledPackages correctly', () => {
 
     expect(result).toEqual([]);
   });
+
+  it('overrides with bundledPackages', () => {
+    vi.spyOn(fs, 'readFileSync').mockImplementation(() =>
+      JSON.stringify(commonPkgJson),
+    );
+
+    const result = calcBundledPackages({
+      autoExternal: true,
+      cwd: 'pkg/to/root',
+      overrideBundledPackages: ['foo', '@bar/*'],
+    });
+
+    expect(result).toEqual(['foo', '@bar/*']);
+  });
 });

pnpm-lock.yaml

@@ -0,0 +1,9 @@
+{
+  "name": "dts-bundle-bundled-packages-test",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@vitest/expect": "3.1.4"
+  }
+}

tests/integration/dts/bundle/bundled-packages/package.json

@@ -0,0 +1,41 @@
+import { defineConfig } from '@rslib/core';
+import { generateBundleEsmConfig } from 'test-helper';
+
+export default defineConfig({
+  lib: [
+    generateBundleEsmConfig({
+      dts: {
+        bundle: true,
+      },
+      output: {
+        distPath: {
+          root: './dist/esm/default',
+        },
+      },
+    }),
+    generateBundleEsmConfig({
+      dts: {
+        bundle: {
+          bundledPackages: [],
+        },
+      },
+      output: {
+        distPath: {
+          root: './dist/esm/override-empty-array',
+        },
+      },
+    }),
+    generateBundleEsmConfig({
+      dts: {
+        bundle: {
+          bundledPackages: ['@vitest/expect', '@vitest/utils'],
+        },
+      },
+      output: {
+        distPath: {
+          root: './dist/esm/override-array-string',
+        },
+      },
+    }),
+  ],
+});

tests/integration/dts/bundle/bundled-packages/rslib.config.ts

@@ -0,0 +1 @@
+export * from '@vitest/expect';

tests/integration/dts/bundle/bundled-packages/src/index.ts

@@ -0,0 +1,7 @@
+{
+  "extends": "@rslib/tsconfig/base",
+  "compilerOptions": {
+    "baseUrl": "./"
+  },
+  "include": ["src"]
+}