refactor: optimize dts logs/docs with declaration files keyword (#817)

Author: Timeless0911

packages/core/src/types/config.ts

@@ -45,31 +45,31 @@ export type Syntax =
 export type Dts =
   | {
       /**
-       * Whether to bundle the DTS files.
+       * Whether to bundle the declaration files.
        * @defaultValue `false`
        * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbundle}
        */
       bundle?: boolean;
       /**
-       * The output directory of DTS files.
+       * The output directory of declaration files.
        * @defaultValue {@link https://lib.rsbuild.dev/config/lib/dts#default-value}
        * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsdistpath}
        */
       distPath?: string;
       /**
-       * Whether to generate DTS files with building the project references.
+       * Whether to generate declaration files with building the project references.
        * @defaultValue `false`
        * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsbuild}
        */
       build?: boolean;
       /**
-       * Whether to abort the build process when an error occurs during DTS generation.
+       * Whether to abort the build process when an error occurs during declaration files generation.
        * @defaultValue `true`
        * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsabortonerror}
        */
       abortOnError?: boolean;
       /**
-       * Whether to automatically set the DTS file extension based on the {@link format} option.
+       * Whether to automatically set the declaration file extension based on the {@link format} option.
        * @defaultValue `false`
        * @see {@link https://lib.rsbuild.dev/config/lib/dts#dtsautoextension}
        */
@@ -251,13 +251,13 @@ export interface LibConfig extends EnvironmentConfig {
    */
   externalHelpers?: boolean;
   /**
-   * Inject content into the top of each JavaScript, CSS or DTS file.
+   * Inject content into the top of each JavaScript, CSS or declaration file.
    * @defaultValue `{}`
    * @see {@link https://lib.rsbuild.dev/config/lib/banner}
    */
   banner?: BannerAndFooter;
   /**
-   * Inject content into the bottom of each JavaScript, CSS or DTS file.
+   * Inject content into the bottom of each JavaScript, CSS or declaration file.
    * @defaultValue `{}`
    * @see {@link https://lib.rsbuild.dev/config/lib/footer}
    */

packages/plugin-dts/README.md

@@ -8,7 +8,7 @@ An [Rsbuild plugin](https://www.npmjs.com/package/rsbuild-plugin-dts) to emit de
 
 ## Using in Rslib
 
-Read [DTS](https://lib.rsbuild.dev/guide/advanced/dts) and [lib.dts](https://lib.rsbuild.dev/config/lib/dts) for more details.
+Read [Declaration files](https://lib.rsbuild.dev/guide/advanced/dts) and [lib.dts](https://lib.rsbuild.dev/config/lib/dts) for more details.
 
 ## Using in Rsbuild
 
@@ -36,11 +36,11 @@ export default {
 - **Type:** `boolean`
 - **Default:** `false`
 
-Whether to bundle the DTS files.
+Whether to bundle the declaration files.
 
-If you want to [bundle DTS](https://lib.rsbuild.dev/guide/advanced/dts#bundle-dts) files, you should:
+If you want to [bundle declaration files](https://lib.rsbuild.dev/guide/advanced/dts#bundle-declaration-files) 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` as a development dependency, which is the underlying tool used for bundling declaration files.
 
 ```bash
 npm add @microsoft/api-extractor -D
@@ -58,7 +58,7 @@ pluginDts({
 
 - **Type:** `string`
 
-The output directory of DTS files. The default value follows the priority below:
+The output directory of declaration files. The default value follows the priority below:
 
 1. The `distPath` value of the plugin options.
 2. The `declarationDir` value in the `tsconfig.json` file.
@@ -75,7 +75,7 @@ pluginDts({
 - **Type:** `boolean`
 - **Default:** `false`
 
-Whether to generate DTS files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
+Whether to generate declaration files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.
 
 When this option is enabled, you must explicitly set `declarationDir` or `outDir` in `tsconfig.json` in order to meet the build requirements.
 
@@ -84,7 +84,7 @@ When this option is enabled, you must explicitly set `declarationDir` or `outDir
 - **Type:** `boolean`
 - **Default:** `true`
 
-Whether to abort the build process when an error occurs during DTS generation.
+Whether to abort the build process when an error occurs during declaration files generation.
 
 By default, type errors will cause the build to fail.
 
@@ -101,7 +101,7 @@ pluginDts({
 - **Type:** `string`
 - **Default:** `'.d.ts'`
 
-The extension of the DTS file.
+The extension of the declaration file.
 
 ```js
 pluginDts({
@@ -114,7 +114,7 @@ pluginDts({
 - **Type:** `boolean`
 - **Default:** `true`
 
-Whether to automatically externalize dependencies of different dependency types and do not bundle them into the DTS file.
+Whether to automatically externalize dependencies of different dependency types and do not bundle them into the declaration file.
 
 The default value of `autoExternal` is `true`, which means the following dependency types will not be bundled:
 
@@ -142,7 +142,7 @@ pluginDts({
 - **Type:** `string`
 - **Default:** `undefined`
 
-Inject content into the top of each DTS file.
+Inject content into the top of each declaration file.
 
 ```js
 pluginDts({
@@ -155,7 +155,7 @@ pluginDts({
 - **Type:** `string`
 - **Default:** `undefined`
 
-Inject content into the bottom of each DTS file.
+Inject content into the bottom of each declaration file.
 
 ```js
 pluginDts({
@@ -201,7 +201,7 @@ pluginDts({
 
 Whether to automatically redirect the import paths of TypeScript declaration output files.
 
-- When set to `true`, Rslib will redirect the import path in the DTS output file to the corresponding relative path based on the [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) configured in `tsconfig.json`.
+- When set to `true`, Rslib will redirect the import path in the declaration output file to the corresponding relative path based on the [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) configured in `tsconfig.json`.
 
 ```ts
 // `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }`
@@ -221,7 +221,7 @@ import { foo } from '../foo'; // expected output './dist/utils/index.d.ts'
 
 Whether to automatically redirect the file extension to import paths based on the TypeScript declaration output files.
 
-- When set to `true`, the import paths in DTS files will be redirected to the corresponding JavaScript extension which can be resolved to corresponding DTS file. The extension of the DTS output file is related to the `dtsExtension` configuration.
+- When set to `true`, the import paths in declaration files will be redirected to the corresponding JavaScript extension which can be resolved to corresponding declaration file. The extension of the declaration output file is related to the `dtsExtension` configuration.
 
 ```ts
 // `dtsExtension` is set to `.d.mts`

packages/plugin-dts/src/apiExtractor.ts

@@ -76,12 +76,11 @@ export async function bundleDts(options: BundleOptions): Promise<void> {
         await addBannerAndFooter(untrimmedFilePath, banner, footer);
 
         logger.info(
-          `API Extractor bundle DTS succeeded: ${color.cyan(untrimmedFilePath)} in ${getTimeCost(start)} ${color.gray(`(${name})`)}`,
+          `bundle declaration files succeeded: ${color.cyan(untrimmedFilePath)} in ${getTimeCost(start)} ${color.gray(`(${name})`)}`,
         );
       }),
     );
   } catch (e) {
-    logger.error('API Extractor Error');
-    throw new Error(`${e}`);
+    throw new Error(`API Extractor Error:\n ${e}`);
   }
 }

packages/plugin-dts/src/dts.ts

@@ -126,7 +126,7 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
       extension: false,
     },
   } = data;
-  logger.start(`Generating DTS... ${color.gray(`(${name})`)}`);
+  logger.start(`generating declaration files... ${color.gray(`(${name})`)}`);
 
   const { options: rawCompilerOptions, fileNames } = tsConfigResult;
 
@@ -147,7 +147,7 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
   );
 
   if (build) {
-    // do not allow to use bundle DTS when 'build: true' since temp declarationDir should be set by user in tsconfig
+    // do not allow to use bundle declaration files when 'build: true' since temp declarationDir should be set by user in tsconfig
     if (bundle) {
       throw Error(`Can not set "dts.bundle: true" when "dts.build: true"`);
     }

packages/plugin-dts/src/index.ts

@@ -89,7 +89,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
 
         const { config } = environment;
 
-        // @microsoft/api-extractor only support single entry to bundle DTS
+        // @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(
@@ -171,7 +171,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
               } else if (message === 'error') {
                 resolve({
                   status: 'error',
-                  errorMessage: `Error occurred in ${environment.name} DTS generation`,
+                  errorMessage: `Error occurred in ${environment.name} declaration files generation.`,
                 });
               }
             });
@@ -188,7 +188,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
 
         promisesResult = await Promise.all(dtsPromises);
       },
-      // Set the order to 'pre' to ensure that when DTS files of multiple formats are generated simultaneously,
+      // Set the order to 'pre' to ensure that when declaration files of multiple formats are generated simultaneously,
       // all errors are thrown together before exiting the process.
       order: 'pre',
     });
@@ -205,7 +205,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
           }
           result.errorMessage && logger.error(result.errorMessage);
           logger.warn(
-            'With the `abortOnError` configuration currently turned off, type errors do not cause build failures, but they do not guarantee proper type file output.',
+            'With `abortOnError` configuration currently disabled, type errors will not fail the build, but proper type declaration output cannot be guaranteed.',
           );
         }
       }

packages/plugin-dts/src/tsc.ts

@@ -4,6 +4,8 @@ import ts from 'typescript';
 import type { DtsRedirect } from './index';
 import { getFileLoc, getTimeCost, processDtsFiles } from './utils';
 
+const logPrefix = color.dim('[tsc]');
+
 export type EmitDtsOptions = {
   name: string;
   cwd: string;
@@ -53,15 +55,13 @@ async function handleDiagnosticsAndProcessFiles(
   );
 
   if (diagnosticMessages.length) {
-    logger.error(
-      `Failed to emit declaration files. ${color.gray(`(${name})`)}`,
-    );
-
     for (const message of diagnosticMessages) {
-      logger.error(message);
+      logger.error(logPrefix, message);
     }
 
-    throw new Error('DTS generation failed');
+    throw new Error(
+      `Failed to generate declaration files. ${color.gray(`(${name})`)}`,
+    );
   }
 }
 
@@ -110,6 +110,7 @@ export async function emitDts(
     const fileLoc = getFileLoc(diagnostic, configPath);
 
     logger.error(
+      logPrefix,
       `${fileLoc} - ${color.red('error')} ${color.gray(`TS${diagnostic.code}:`)}`,
       ts.flattenDiagnosticMessageText(
         diagnostic.messageText,
@@ -132,16 +133,16 @@ export async function emitDts(
     // 6031: File change detected. Starting incremental compilation...
     // 6032: Starting compilation in watch mode...
     if (diagnostic.code === 6031 || diagnostic.code === 6032) {
-      logger.info(message);
+      logger.info(logPrefix, message);
     }
 
     // 6194: 0 errors or 2+ errors!
     if (diagnostic.code === 6194) {
       if (errorCount === 0 || !errorCount) {
-        logger.info(message);
+        logger.info(logPrefix, message);
         onComplete(true);
       } else {
-        logger.error(message);
+        logger.error(logPrefix, message);
       }
       await processDtsFiles(
         bundle,
@@ -157,7 +158,7 @@ export async function emitDts(
 
     // 6193: 1 error
     if (diagnostic.code === 6193) {
-      logger.error(message);
+      logger.error(logPrefix, message);
       await processDtsFiles(
         bundle,
         declarationDir,
@@ -277,16 +278,14 @@ export async function emitDts(
       );
 
       if (errorNumber > 0) {
-        logger.error(
-          `Failed to emit declaration files. ${color.gray(`(${name})`)}`,
+        throw new Error(
+          `Failed to generate declaration files. ${color.gray(`(${name})`)}`,
         );
-
-        throw new Error('DTS generation failed');
       }
     }
 
     logger.ready(
-      `DTS generated in ${getTimeCost(start)} ${color.gray(`(${name})`)}`,
+      `declaration files generated in ${getTimeCost(start)} ${color.gray(`(${name})`)}`,
     );
   } else {
     // watch mode, can also deal with incremental build

packages/plugin-dts/src/utils.ts

@@ -398,7 +398,7 @@ export async function processDtsFiles(
       const newFile = file.replace('.d.ts', dtsExtension);
       fs.renameSync(file, newFile);
     } catch (error) {
-      logger.error(`Error renaming DTS file ${file}: ${error}`);
+      logger.error(`Failed to rename declaration file ${file}: ${error}`);
     }
   }
 }
@@ -424,7 +424,7 @@ export function processSourceEntry(
   }
 
   throw new Error(
-    '@microsoft/api-extractor only support entry of Record<string, string> type to bundle DTS, please check your entry config.',
+    '@microsoft/api-extractor only support entry of Record<string, string> type to bundle declaration files, please check your entry config.',
   );
 }
 

tests/integration/dts/index.test.ts

@@ -464,7 +464,9 @@ describe('dts when build: true', () => {
       });
     } catch (err: any) {
       // not easy to proxy child process stdout
-      expect(err.message).toBe('Error occurred in esm DTS generation');
+      expect(err.message).toBe(
+        'Error occurred in esm declaration files generation.',
+      );
     }
   });
 

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

@@ -16,7 +16,7 @@ type Banner = {
 
 - **Default:** `{}`
 
-Inject content into the top of each JavaScript, CSS or DTS output file.
+Inject content into the top of each JavaScript, CSS or declaration output file.
 
 ## Object type
 
@@ -39,7 +39,7 @@ Inject content into the top of each CSS output file.
 - **Type:** `string`
 - **Default:** `undefined`
 
-Inject content into the top of each DTS output file.
+Inject content into the top of each declaration output file.
 
 ## Notice
 
@@ -73,6 +73,6 @@ export default {
 
 :::warning
 
-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.
+The banner content in declaration 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.
 
 :::

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

@@ -75,7 +75,7 @@ export default {
 
 ::: note
 
-If [DTS generation](/config/lib/dts) is enabled, remember to set [exclude](https://www.typescriptlang.org/tsconfig/#exclude) field in `tsconfig.json` to avoid generating TypeScript declaration files for the corresponding files.
+If [declaration files generation](/config/lib/dts) is enabled, remember to set [exclude](https://www.typescriptlang.org/tsconfig/#exclude) field in `tsconfig.json` to avoid generating TypeScript declaration files for the corresponding files.
 
 For example, exclude test files within the `src` folder: