feat: support DTS redirect (#742)

Author: Timeless0911

packages/core/src/config.ts

@@ -1217,7 +1217,7 @@ const composeDtsConfig = async (
   libConfig: LibConfig,
   dtsExtension: string,
 ): Promise<EnvironmentConfig> => {
-  const { format, autoExternal, banner, footer } = libConfig;
+  const { format, autoExternal, banner, footer, redirect } = libConfig;
 
   let { dts } = libConfig;
 
@@ -1243,6 +1243,7 @@ const composeDtsConfig = async (
         autoExternal: getAutoExternalDefaultValue(format!, autoExternal),
         banner: banner?.dts,
         footer: footer?.dts,
+        redirect: redirect?.dts,
       }),
     ],
   };

packages/core/src/types/config.ts

@@ -177,9 +177,16 @@ export type StyleRedirect = {
   extension?: boolean;
 };
 
-// @ts-expect-error TODO: support dts redirect in the future
-type DtsRedirect = {
+export type DtsRedirect = {
+  /**
+   * Whether to automatically redirect the import paths of TypeScript declaration output files.
+   * @defaultValue `true`
+   */
   path?: boolean;
+  /**
+   * Whether to automatically redirect the file extension to import paths based on the TypeScript declaration output files.
+   * @defaultValue `false`
+   */
   extension?: boolean;
 };
 
@@ -190,7 +197,8 @@ export type Redirect = {
   style?: StyleRedirect;
   /** Controls the redirect of the import paths of output asset files. */
   asset?: boolean;
-  // dts?: DtsRedirect;
+  /** Controls the redirect of the import paths of output TypeScript declaration files. */
+  dts?: DtsRedirect;
 };
 
 export interface LibConfig extends EnvironmentConfig {

packages/plugin-dts/README.md

@@ -163,6 +163,77 @@ pluginDts({
 });
 ```
 
+### redirect
+
+- **Type:**
+
+```ts
+type DtsRedirect = {
+  path?: boolean;
+  extension?: boolean;
+};
+```
+
+- **Default:**
+
+```ts
+const defaultRedirect = {
+  path: true,
+  extension: false,
+};
+```
+
+Controls the redirect of the import paths of output TypeScript declaration files.
+
+```js
+pluginDts({
+  redirect: {
+    path: true,
+    extension: false,
+  },
+});
+```
+
+#### redirect.path
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+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`.
+
+```ts
+// `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }`
+import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
+import { foo } from './foo'; // expected output of './dist/bar.d.ts'
+
+import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
+import { foo } from '../foo'; // expected output './dist/utils/index.d.ts'
+```
+
+- When set to `false`, the original import path will remain unchanged.
+
+#### redirect.extension
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+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.
+
+```ts
+// `dtsExtension` is set to `.d.mts`
+import { foo } from './foo'; // source code of './src/bar.ts' ↓
+import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'
+
+import { foo } from './foo.ts'; // source code of './src/utils/index.ts' ↓
+import { foo } from './foo.mjs'; // expected output './dist/utils/index.d.mts'
+```
+
+- When set to `false`, the file extension will remain unchanged from the original import path in the rewritten import path of the output file (regardless of whether it is specified or specified as any value).
+
 ## Contributing
 
 Please read the [Contributing Guide](https://github.com/web-infra-dev/rslib/blob/main/CONTRIBUTING.md).

packages/plugin-dts/package.json

@@ -29,9 +29,11 @@
     "dev": "rslib build --watch"
   },
   "dependencies": {
+    "@ast-grep/napi": "^0.34.4",
     "magic-string": "^0.30.17",
     "picocolors": "1.1.1",
-    "tinyglobby": "^0.2.10"
+    "tinyglobby": "^0.2.10",
+    "tsconfig-paths": "^4.2.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",

packages/plugin-dts/src/dts.ts

@@ -129,6 +129,10 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
     userExternals,
     banner,
     footer,
+    redirect = {
+      path: true,
+      extension: false,
+    },
   } = data;
   logger.start(`Generating DTS... ${color.gray(`(${name})`)}`);
 
@@ -252,6 +256,8 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
       tsConfigResult,
       declarationDir,
       dtsExtension,
+      redirect,
+      rootDir,
       banner,
       footer,
     },

packages/plugin-dts/src/index.ts

@@ -9,6 +9,11 @@ import { loadTsconfig, processSourceEntry } from './utils';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+export type DtsRedirect = {
+  path?: boolean;
+  extension?: boolean;
+};
+
 export type PluginDtsOptions = {
   bundle?: boolean;
   distPath?: string;
@@ -24,6 +29,7 @@ export type PluginDtsOptions = {
       };
   banner?: string;
   footer?: string;
+  redirect?: DtsRedirect;
 };
 
 export type DtsEntry = {
@@ -53,14 +59,16 @@ export const PLUGIN_DTS_NAME = 'rsbuild:dts';
 
 // use ts compiler API to generate bundleless dts
 // use ts compiler API and api-extractor to generate dts bundle
-// TODO: deal alias in dts
 export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
   name: PLUGIN_DTS_NAME,
 
   setup(api) {
     options.bundle = options.bundle ?? false;
     options.abortOnError = options.abortOnError ?? true;
     options.build = options.build ?? false;
+    options.redirect = options.redirect ?? {};
+    options.redirect.path = options.redirect.path ?? true;
+    options.redirect.extension = options.redirect.extension ?? false;
 
     const dtsPromises: Promise<TaskResult>[] = [];
     let promisesResult: TaskResult[] = [];

packages/plugin-dts/src/tsc.ts

@@ -1,6 +1,7 @@
 import { logger } from '@rsbuild/core';
 import color from 'picocolors';
 import ts from 'typescript';
+import type { DtsRedirect } from './index';
 import { getFileLoc, getTimeCost, processDtsFiles } from './utils';
 
 export type EmitDtsOptions = {
@@ -10,6 +11,8 @@ export type EmitDtsOptions = {
   tsConfigResult: ts.ParsedCommandLine;
   declarationDir: string;
   dtsExtension: string;
+  rootDir: string;
+  redirect: DtsRedirect;
   banner?: string;
   footer?: string;
 };
@@ -21,6 +24,8 @@ async function handleDiagnosticsAndProcessFiles(
   bundle: boolean,
   declarationDir: string,
   dtsExtension: string,
+  redirect: DtsRedirect,
+  rootDir: string,
   banner?: string,
   footer?: string,
   name?: string,
@@ -36,7 +41,16 @@ async function handleDiagnosticsAndProcessFiles(
     diagnosticMessages.push(message);
   }
 
-  await processDtsFiles(bundle, declarationDir, dtsExtension, banner, footer);
+  await processDtsFiles(
+    bundle,
+    declarationDir,
+    dtsExtension,
+    redirect,
+    configPath,
+    rootDir,
+    banner,
+    footer,
+  );
 
   if (diagnosticMessages.length) {
     logger.error(
@@ -65,8 +79,10 @@ export async function emitDts(
     declarationDir,
     name,
     dtsExtension,
+    rootDir,
     banner,
     footer,
+    redirect,
   } = options;
   const {
     options: rawCompilerOptions,
@@ -131,6 +147,9 @@ export async function emitDts(
         bundle,
         declarationDir,
         dtsExtension,
+        redirect,
+        configPath,
+        rootDir,
         banner,
         footer,
       );
@@ -143,6 +162,9 @@ export async function emitDts(
         bundle,
         declarationDir,
         dtsExtension,
+        redirect,
+        configPath,
+        rootDir,
         banner,
         footer,
       );
@@ -179,6 +201,8 @@ export async function emitDts(
         bundle,
         declarationDir,
         dtsExtension,
+        redirect,
+        rootDir,
         banner,
         footer,
         name,
@@ -211,6 +235,8 @@ export async function emitDts(
         bundle,
         declarationDir,
         dtsExtension,
+        redirect,
+        rootDir,
         banner,
         footer,
         name,
@@ -243,6 +269,9 @@ export async function emitDts(
         bundle,
         declarationDir,
         dtsExtension,
+        redirect,
+        configPath,
+        rootDir,
         banner,
         footer,
       );