From 89e11ced151bfaed3c1e16357693047f931b2cc6 Mon Sep 17 00:00:00 2001
From: Timeless0911 <1604889533@qq.com>
Date: Tue, 29 Jul 2025 16:56:42 +0800
Subject: [PATCH 1/4] feat(dts): support `dts.alias`

---
 packages/core/src/config.ts                   |  1 +
 packages/core/src/types/config.ts             |  6 ++++
 packages/plugin-dts/README.md                 | 19 ++++++++++++
 packages/plugin-dts/src/dts.ts                | 17 ++++++++++-
 packages/plugin-dts/src/index.ts              |  2 ++
 packages/plugin-dts/src/tsc.ts                |  9 ++++++
 packages/plugin-dts/src/utils.ts              | 30 +++++++++++++++++--
 pnpm-lock.yaml                                | 11 +++++++
 .../alias/compile/express/index.d.ts          |  4 +++
 .../alias/compile/express/index.js            |  3 ++
 .../alias/compile/express/package.json        |  5 ++++
 .../dts/bundle-false/alias/package.json       | 10 +++++++
 .../dts/bundle-false/alias/rslib.config.ts    | 23 ++++++++++++++
 .../dts/bundle-false/alias/src/index.ts       |  1 +
 .../dts/bundle-false/alias/tsconfig.json      |  7 +++++
 website/docs/en/config/lib/dts.mdx            | 27 +++++++++++++++++
 website/docs/en/guide/advanced/dts.mdx        |  1 +
 website/docs/zh/config/lib/dts.mdx            | 27 +++++++++++++++++
 website/docs/zh/guide/advanced/dts.mdx        |  1 +
 19 files changed, 201 insertions(+), 3 deletions(-)
 create mode 100644 tests/integration/dts/bundle-false/alias/compile/express/index.d.ts
 create mode 100644 tests/integration/dts/bundle-false/alias/compile/express/index.js
 create mode 100644 tests/integration/dts/bundle-false/alias/compile/express/package.json
 create mode 100644 tests/integration/dts/bundle-false/alias/package.json
 create mode 100644 tests/integration/dts/bundle-false/alias/rslib.config.ts
 create mode 100644 tests/integration/dts/bundle-false/alias/src/index.ts
 create mode 100644 tests/integration/dts/bundle-false/alias/tsconfig.json

diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index 43f224624..7fc34e919 100644
--- a/packages/core/src/config.ts
+++ b/packages/core/src/config.ts
@@ -1416,6 +1416,7 @@ const composeDtsConfig = async (
         abortOnError: dts?.abortOnError,
         dtsExtension: dts?.autoExtension ? dtsExtension : '.d.ts',
         autoExternal: getAutoExternalDefaultValue(format, autoExternal),
+        alias: dts?.alias,
         banner: banner?.dts,
         footer: footer?.dts,
         redirect: redirect?.dts,
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
index e1f973884..3ba8f7b96 100644
--- a/packages/core/src/types/config.ts
+++ b/packages/core/src/types/config.ts
@@ -88,6 +88,12 @@ export type Dts =
        * @see {@link https://rslib.rs/config/lib/dts#dtsautoextension}
        */
       autoExtension?: boolean;
+      // Set the alias for the module path, similar to the `paths` option in `tsconfig.json`.
+      /**
+       * @defaultValue `{}`
+       * @see {@link https://rslib.rs/config/lib/dts#dtsalias}
+       */
+      alias?: Record<string, string>;
     }
   | boolean;
 
diff --git a/packages/plugin-dts/README.md b/packages/plugin-dts/README.md
index 50daa7116..ff50c052f 100644
--- a/packages/plugin-dts/README.md
+++ b/packages/plugin-dts/README.md
@@ -136,6 +136,25 @@ pluginDts({
 });
 ```
 
+### alias
+
+- **Type:**` Record<string, string>`
+- **Default:** `{}`
+
+Configure the path alias for declaration files.
+
+`alias` will be merged with `compilerOptions.paths` configured in `tsconfig.json` and `alias` has a higher priority.
+
+In most cases, you don't need to use `alias`, but consider using it when you need to use path alias only in declaration files without wanting to affect JavaScript outputs. For example, map the declaration file of `foo` to `./compiled/foo`.
+
+```js
+pluginDts({
+  alias: {
+    foo: './compiled/foo',
+  },
+});
+```
+
 ### autoExternal
 
 - **Type:** `boolean`
diff --git a/packages/plugin-dts/src/dts.ts b/packages/plugin-dts/src/dts.ts
index 4173cffeb..f2e749442 100644
--- a/packages/plugin-dts/src/dts.ts
+++ b/packages/plugin-dts/src/dts.ts
@@ -12,7 +12,11 @@ import { logger } from '@rsbuild/core';
 import color from 'picocolors';
 import type { DtsEntry, DtsGenOptions } from './index';
 import { emitDts } from './tsc';
-import { calcLongestCommonPath, ensureTempDeclarationDir } from './utils';
+import {
+  calcLongestCommonPath,
+  ensureTempDeclarationDir,
+  mergeAliasWithTsConfigPaths,
+} from './utils';
 
 const isObject = (obj: unknown): obj is Record<string, any> =>
   Object.prototype.toString.call(obj) === '[object Object]';
@@ -123,6 +127,7 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
     isWatch,
     dtsExtension = '.d.ts',
     autoExternal = true,
+    alias = {},
     userExternals,
     apiExtractorOptions,
     banner,
@@ -136,6 +141,15 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
     logger.start(`generating declaration files... ${color.gray(`(${name})`)}`);
   }
 
+  // merge alias and tsconfig paths
+  const paths = mergeAliasWithTsConfigPaths(
+    tsConfigResult.options.paths,
+    alias,
+  );
+  if (Object.keys(paths).length > 0) {
+    tsConfigResult.options.paths = paths;
+  }
+
   const { options: rawCompilerOptions, fileNames } = tsConfigResult;
 
   // The longest common path of all non-declaration input files.
@@ -240,6 +254,7 @@ export async function generateDts(data: DtsGenOptions): Promise<void> {
       dtsExtension,
       redirect,
       rootDir,
+      paths,
       banner,
       footer,
     },
diff --git a/packages/plugin-dts/src/index.ts b/packages/plugin-dts/src/index.ts
index 602fcc918..9eb410d60 100644
--- a/packages/plugin-dts/src/index.ts
+++ b/packages/plugin-dts/src/index.ts
@@ -32,6 +32,7 @@ export type PluginDtsOptions = {
   build?: boolean;
   abortOnError?: boolean;
   dtsExtension?: string;
+  alias?: Record<string, string>;
   autoExternal?:
     | boolean
     | {
@@ -91,6 +92,7 @@ export const pluginDts = (options: PluginDtsOptions = {}): RsbuildPlugin => ({
     options.redirect = options.redirect ?? {};
     options.redirect.path = options.redirect.path ?? true;
     options.redirect.extension = options.redirect.extension ?? false;
+    options.alias = options.alias ?? {};
 
     const dtsPromises: Promise<TaskResult>[] = [];
     let promisesResult: TaskResult[] = [];
diff --git a/packages/plugin-dts/src/tsc.ts b/packages/plugin-dts/src/tsc.ts
index 31290eac9..fe44a0ed6 100644
--- a/packages/plugin-dts/src/tsc.ts
+++ b/packages/plugin-dts/src/tsc.ts
@@ -21,6 +21,7 @@ export type EmitDtsOptions = {
   dtsExtension: string;
   rootDir: string;
   redirect: DtsRedirect;
+  paths: Record<string, string[]>;
   banner?: string;
   footer?: string;
 };
@@ -33,6 +34,7 @@ async function handleDiagnosticsAndProcessFiles(
   dtsExtension: string,
   redirect: DtsRedirect,
   rootDir: string,
+  paths: Record<string, string[]>,
   banner?: string,
   footer?: string,
   name?: string,
@@ -54,6 +56,7 @@ async function handleDiagnosticsAndProcessFiles(
     redirect,
     configPath,
     rootDir,
+    paths,
     banner,
     footer,
   );
@@ -89,6 +92,7 @@ export async function emitDts(
     rootDir,
     banner,
     footer,
+    paths,
     redirect,
   } = options;
   const {
@@ -147,6 +151,7 @@ export async function emitDts(
         redirect,
         configPath,
         rootDir,
+        paths,
         banner,
         footer,
       );
@@ -162,6 +167,7 @@ export async function emitDts(
         redirect,
         configPath,
         rootDir,
+        paths,
         banner,
         footer,
       );
@@ -230,6 +236,7 @@ export async function emitDts(
         dtsExtension,
         redirect,
         rootDir,
+        paths,
         banner,
         footer,
         name,
@@ -291,6 +298,7 @@ export async function emitDts(
         dtsExtension,
         redirect,
         rootDir,
+        paths,
         banner,
         footer,
         name,
@@ -326,6 +334,7 @@ export async function emitDts(
         redirect,
         configPath,
         rootDir,
+        paths,
         banner,
         footer,
       );
diff --git a/packages/plugin-dts/src/utils.ts b/packages/plugin-dts/src/utils.ts
index 4b1f264a6..08d1bc1d1 100644
--- a/packages/plugin-dts/src/utils.ts
+++ b/packages/plugin-dts/src/utils.ts
@@ -51,6 +51,31 @@ export function loadTsconfig(tsconfigPath: string): ts.ParsedCommandLine {
   return configFileContent;
 }
 
+export function mergeAliasWithTsConfigPaths(
+  paths: Record<string, string[]> | undefined,
+  alias: Record<string, string> = {},
+): Record<string, string[]> {
+  const mergedPaths: Record<string, string[]> = {};
+
+  if (paths) {
+    for (const [key, value] of Object.entries(paths)) {
+      if (Array.isArray(value) && value.length > 0) {
+        mergedPaths[key] = [...value];
+      }
+    }
+  }
+
+  if (alias && typeof alias === 'object' && Object.keys(alias).length > 0) {
+    for (const [key, value] of Object.entries(alias)) {
+      if (typeof value === 'string' && value.trim()) {
+        mergedPaths[key] = [value];
+      }
+    }
+  }
+
+  return Object.keys(mergedPaths).length > 0 ? mergedPaths : {};
+}
+
 export const TEMP_FOLDER = '.rslib';
 export const TEMP_DTS_DIR: string = `${TEMP_FOLDER}/declarations`;
 
@@ -395,6 +420,7 @@ export async function processDtsFiles(
   redirect: DtsRedirect,
   tsconfigPath: string,
   rootDir: string,
+  paths: Record<string, string[]>,
   banner?: string,
   footer?: string,
 ): Promise<void> {
@@ -412,11 +438,11 @@ export async function processDtsFiles(
       return;
     }
 
-    const { absoluteBaseUrl, paths, addMatchAll } = result;
+    const { absoluteBaseUrl, addMatchAll } = result;
     const mainFields: string[] = [];
     /**
      * resolve paths priorities:
-     * see https://github.com/jonaskello/tsconfig-paths/blob/098e066632f5b9f35c956803fe60d17ffc60b688/src/match-path-sync.ts#L18-L26
+     * see https://github.com/jonaskello/tsconfig-paths/blob/098e066632f5b9f35c956803fe60d17ffc60b688/src/try-path.ts#L11-L17
      */
     matchPath = createMatchPath(
       absoluteBaseUrl,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5c72c3bb2..789dca217 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -723,6 +723,17 @@ importers:
 
   tests/integration/dts/bundle-false/abort-on-error: {}
 
+  tests/integration/dts/bundle-false/alias:
+    devDependencies:
+      '@types/express':
+        specifier: ^5.0.3
+        version: 5.0.3
+      express:
+        specifier: ^5.1.0
+        version: 5.1.0
+
+  tests/integration/dts/bundle-false/alias/compile/express: {}
+
   tests/integration/dts/bundle-false/auto-extension: {}
 
   tests/integration/dts/bundle-false/basic: {}
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/index.d.ts b/tests/integration/dts/bundle-false/alias/compile/express/index.d.ts
new file mode 100644
index 000000000..4c82305cf
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/compile/express/index.d.ts
@@ -0,0 +1,4 @@
+export declare function logger(): {
+  (...data: any[]): void;
+  (message?: any, ...optionalParams: any[]): void;
+};
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/index.js b/tests/integration/dts/bundle-false/alias/compile/express/index.js
new file mode 100644
index 000000000..55cdb9deb
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/compile/express/index.js
@@ -0,0 +1,3 @@
+export function logger() {
+  return console.log;
+}
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/package.json b/tests/integration/dts/bundle-false/alias/compile/express/package.json
new file mode 100644
index 000000000..d8ebb18eb
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/compile/express/package.json
@@ -0,0 +1,5 @@
+{
+  "name": "express",
+  "version": "0.0.0",
+  "private": true
+}
diff --git a/tests/integration/dts/bundle-false/alias/package.json b/tests/integration/dts/bundle-false/alias/package.json
new file mode 100644
index 000000000..316782849
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/package.json
@@ -0,0 +1,10 @@
+{
+  "name": "dts-bundle-false-alias-test",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@types/express": "^5.0.3",
+    "express": "^5.1.0"
+  }
+}
diff --git a/tests/integration/dts/bundle-false/alias/rslib.config.ts b/tests/integration/dts/bundle-false/alias/rslib.config.ts
new file mode 100644
index 000000000..5d34269ed
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/rslib.config.ts
@@ -0,0 +1,23 @@
+import { defineConfig } from '@rslib/core';
+import { generateBundleCjsConfig, generateBundleEsmConfig } from 'test-helper';
+
+export default defineConfig({
+  lib: [
+    generateBundleEsmConfig({
+      dts: {
+        bundle: false,
+        alias: {
+          express: './compile/express',
+        },
+      },
+    }),
+    generateBundleCjsConfig({
+      dts: {
+        bundle: false,
+        alias: {
+          express: './compile/express',
+        },
+      },
+    }),
+  ],
+});
diff --git a/tests/integration/dts/bundle-false/alias/src/index.ts b/tests/integration/dts/bundle-false/alias/src/index.ts
new file mode 100644
index 000000000..77525a3a9
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/src/index.ts
@@ -0,0 +1 @@
+export {} from 'express';
diff --git a/tests/integration/dts/bundle-false/alias/tsconfig.json b/tests/integration/dts/bundle-false/alias/tsconfig.json
new file mode 100644
index 000000000..1d2e6432e
--- /dev/null
+++ b/tests/integration/dts/bundle-false/alias/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}
diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx
index 7afe3bbb5..0ff28456d 100644
--- a/website/docs/en/config/lib/dts.mdx
+++ b/website/docs/en/config/lib/dts.mdx
@@ -14,6 +14,7 @@ type Dts =
       build?: boolean;
       abortOnError?: boolean;
       autoExtension?: boolean;
+      alias?: Record<string, string>;
     }
   | boolean;
 ```
@@ -218,3 +219,29 @@ When `dts.autoExtension` is set to `true`, the declaration file extension will b
 It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.
 
 :::
+
+### dts.alias
+
+- **Type:**` Record<string, string>`
+- **Default:** `{}`
+
+Configure the path alias for declaration files.
+
+`dts.alias` will be merged with `compilerOptions.paths` configured in `tsconfig.json` and `dts.alias` has a higher priority.
+
+In most cases, you don't need to use `dts.alias`, but consider using it when you need to use path alias only in declaration files without wanting to affect JavaScript outputs. For example, map the declaration file of `foo` to `./compiled/foo`.
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      // [!code highlight:5]
+      dts: {
+        alias: {
+          foo: './compiled/foo',
+        },
+      },
+    },
+  ],
+};
+```
diff --git a/website/docs/en/guide/advanced/dts.mdx b/website/docs/en/guide/advanced/dts.mdx
index 185e8b3ac..158f2e3ba 100644
--- a/website/docs/en/guide/advanced/dts.mdx
+++ b/website/docs/en/guide/advanced/dts.mdx
@@ -83,6 +83,7 @@ The priority from highest to lowest of final output directory of declaration fil
 | [dts.build](/config/lib/dts#dtsbuild)                               | Whether to generate declaration files with building the project references.                                            |
 | [dts.abortOnError](/config/lib/dts#dtsabortonerror)                 | Whether to abort the build process when an error occurs during declaration files generation.                           |
 | [dts.autoExtension](/config/lib/dts#dtsautoextension)               | Whether to automatically set the declaration file extension based on the [format](/config/lib/format) option.          |
+| [dts.alias](/config/lib/dts#dtsalias)                               | The path alias of the declaration files.                                                                               |
 | [banner.dts](/config/lib/banner#bannerdts)                          | Inject content into the top of each declaration output file.                                                           |
 | [footer.dts](/config/lib/footer#footerdts)                          | Inject content into the bottom of each declaration file.                                                               |
 | [redirect.dts.path](/config/lib/redirect#redirectdtspath)           | Whether to automatically redirect the import paths of TypeScript declaration output files.                             |
diff --git a/website/docs/zh/config/lib/dts.mdx b/website/docs/zh/config/lib/dts.mdx
index 8aff49200..22ec5a1a5 100644
--- a/website/docs/zh/config/lib/dts.mdx
+++ b/website/docs/zh/config/lib/dts.mdx
@@ -14,6 +14,7 @@ type Dts =
       build?: boolean;
       abortOnError?: boolean;
       autoExtension?: boolean;
+      alias?: Record<string, string>;
     }
   | boolean;
 ```
@@ -218,3 +219,29 @@ export default {
 这遵循与 [lib.autoExtension](/config/lib/auto-extension) 相同的逻辑，但默认值不同，因为类型声明文件扩展名可能会在不同的模块解析策略中造成一些问题。
 
 :::
+
+### dts.alias
+
+- **类型：** `Record<string, string>`
+- **默认值：** `{}`
+
+用于配置类型声明文件的路径别名。
+
+`dts.alias` 会与 `tsconfig.json` 中配置的 `compilerOptions.paths` 合并，且 `dts.alias` 具有更高的优先级。
+
+大部分情况下，你不需要使用 `dts.alias`，但当你需要在类型声明文件中使用路径别名却不希望影响 JavaScript 产物时，可以考虑使用它。比如，将 `foo` 的类型声明文件指向 `./compiled/foo`。
+
+```ts title="rslib.config.ts"
+export default {
+  lib: [
+    {
+      // [!code highlight:5]
+      dts: {
+        alias: {
+          foo: './compiled/foo',
+        },
+      },
+    },
+  ],
+};
+```
diff --git a/website/docs/zh/guide/advanced/dts.mdx b/website/docs/zh/guide/advanced/dts.mdx
index 7e92796b4..fb20581e5 100644
--- a/website/docs/zh/guide/advanced/dts.mdx
+++ b/website/docs/zh/guide/advanced/dts.mdx
@@ -83,6 +83,7 @@ import { PackageManagerTabs } from '@theme';
 | [dts.build](/config/lib/dts#dtsbuild)                               | 是否在生成类型声明文件时构建项目的 project references。                |
 | [dts.abortOnError](/config/lib/dts#dtsabortonerror)                 | 当类型声明文件生成过程中出现错误时，是否中止构建过程。                 |
 | [dts.autoExtension](/config/lib/dts#dtsautoextension)               | 是否根据 [format](/config/lib/format) 选项自动设置类型声明文件扩展名。 |
+| [dts.alias](/config/lib/dts#dtsalias)                               | 类型声明文件的路径别名。                                               |
 | [banner.dts](/config/lib/banner#bannerdts)                          | 在每个类型声明文件顶部注入内容。                                       |
 | [footer.dts](/config/lib/footer#footerdts)                          | 在每个类型声明文件底部注入内容。                                       |
 | [redirect.dts.path](/config/lib/redirect#redirectdtspath)           | 是否自动重定向类型声明文件中的导入路径。                               |

From fd934aa33312f05e27096af1799831247dfd9b57 Mon Sep 17 00:00:00 2001
From: Timeless0911 <1604889533@qq.com>
Date: Tue, 29 Jul 2025 17:01:18 +0800
Subject: [PATCH 2/4] chore: update

---
 packages/core/src/types/config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
index 3ba8f7b96..6312f2a1f 100644
--- a/packages/core/src/types/config.ts
+++ b/packages/core/src/types/config.ts
@@ -88,8 +88,8 @@ export type Dts =
        * @see {@link https://rslib.rs/config/lib/dts#dtsautoextension}
        */
       autoExtension?: boolean;
-      // Set the alias for the module path, similar to the `paths` option in `tsconfig.json`.
       /**
+       * Set the alias for declaration files, similar to the `compilerOptions.paths` option in `tsconfig.json`.
        * @defaultValue `{}`
        * @see {@link https://rslib.rs/config/lib/dts#dtsalias}
        */

From 8d64ff43cc7a3c9440420f37fc3a359b7b40c827 Mon Sep 17 00:00:00 2001
From: Timeless0911 <1604889533@qq.com>
Date: Tue, 29 Jul 2025 19:13:17 +0800
Subject: [PATCH 3/4] chore: update

---
 packages/plugin-dts/README.md           |  2 +-
 packages/plugin-dts/src/utils.ts        | 18 ++---
 packages/plugin-dts/tests/utils.test.ts | 89 ++++++++++++++++++++++++-
 pnpm-lock.yaml                          |  4 --
 pnpm-workspace.yaml                     |  1 +
 tests/integration/dts/index.test.ts     | 22 ++++++
 website/docs/en/config/lib/dts.mdx      |  2 +-
 7 files changed, 123 insertions(+), 15 deletions(-)

diff --git a/packages/plugin-dts/README.md b/packages/plugin-dts/README.md
index ff50c052f..15d80cfcc 100644
--- a/packages/plugin-dts/README.md
+++ b/packages/plugin-dts/README.md
@@ -138,7 +138,7 @@ pluginDts({
 
 ### alias
 
-- **Type:**` Record<string, string>`
+- **Type:** `Record<string, string>`
 - **Default:** `{}`
 
 Configure the path alias for declaration files.
diff --git a/packages/plugin-dts/src/utils.ts b/packages/plugin-dts/src/utils.ts
index 08d1bc1d1..e357aaba8 100644
--- a/packages/plugin-dts/src/utils.ts
+++ b/packages/plugin-dts/src/utils.ts
@@ -57,14 +57,6 @@ export function mergeAliasWithTsConfigPaths(
 ): Record<string, string[]> {
   const mergedPaths: Record<string, string[]> = {};
 
-  if (paths) {
-    for (const [key, value] of Object.entries(paths)) {
-      if (Array.isArray(value) && value.length > 0) {
-        mergedPaths[key] = [...value];
-      }
-    }
-  }
-
   if (alias && typeof alias === 'object' && Object.keys(alias).length > 0) {
     for (const [key, value] of Object.entries(alias)) {
       if (typeof value === 'string' && value.trim()) {
@@ -73,6 +65,16 @@ export function mergeAliasWithTsConfigPaths(
     }
   }
 
+  if (paths) {
+    for (const [key, value] of Object.entries(paths)) {
+      if (Array.isArray(value) && value.length > 0) {
+        if (!mergedPaths[key]) {
+          mergedPaths[key] = [...value];
+        }
+      }
+    }
+  }
+
   return Object.keys(mergedPaths).length > 0 ? mergedPaths : {};
 }
 
diff --git a/packages/plugin-dts/tests/utils.test.ts b/packages/plugin-dts/tests/utils.test.ts
index 984bd69ec..7de140eff 100644
--- a/packages/plugin-dts/tests/utils.test.ts
+++ b/packages/plugin-dts/tests/utils.test.ts
@@ -1,5 +1,5 @@
 import { expect, test } from '@rstest/core';
-import { prettyTime } from '../src/utils';
+import { mergeAliasWithTsConfigPaths, prettyTime } from '../src/utils';
 
 test('should pretty time correctly', () => {
   expect(prettyTime(0.0012)).toEqual('0.001 s');
@@ -12,3 +12,90 @@ test('should pretty time correctly', () => {
   expect(prettyTime(1234)).toEqual('20 m 34 s');
   expect(prettyTime(1234.5)).toEqual('20 m 34.5 s');
 });
+
+test('mergeAliasWithTsConfigPaths should handle empty inputs', () => {
+  // Both undefined
+  expect(
+    mergeAliasWithTsConfigPaths(undefined, undefined),
+  ).toMatchInlineSnapshot({}, '{}');
+
+  // Empty objects
+  expect(mergeAliasWithTsConfigPaths({}, {})).toMatchInlineSnapshot({}, '{}');
+
+  // One empty, one undefined
+  expect(mergeAliasWithTsConfigPaths({}, undefined)).toMatchInlineSnapshot(
+    {},
+    '{}',
+  );
+  expect(mergeAliasWithTsConfigPaths(undefined, {})).toMatchInlineSnapshot(
+    {},
+    '{}',
+  );
+});
+
+test('mergeAliasWithTsConfigPaths should handle paths only', () => {
+  const paths = {
+    '@/*': ['./src/*'],
+  };
+
+  const result = mergeAliasWithTsConfigPaths(paths, undefined);
+
+  expect(result).toMatchInlineSnapshot(`
+    {
+      "@/*": [
+        "./src/*",
+      ],
+    }
+  `);
+});
+
+test('mergeAliasWithTsConfigPaths should handle alias only', () => {
+  const alias = {
+    '@': './src',
+  };
+
+  const result = mergeAliasWithTsConfigPaths(undefined, alias);
+
+  expect(result).toMatchInlineSnapshot(`
+    {
+      "@": [
+        "./src",
+      ],
+    }
+  `);
+});
+
+test('mergeAliasWithTsConfigPaths should handle alias overriding paths', () => {
+  const paths = {
+    '@utils/*': ['./lib/utils/*'],
+    '@/*': ['./src/*'],
+  };
+
+  const alias = {
+    '@utils/*': './src/utils',
+    '@components': './src/components',
+  };
+
+  const result = mergeAliasWithTsConfigPaths(paths, alias);
+
+  expect(Object.keys(result)).toMatchInlineSnapshot(`
+    [
+      "@utils/*",
+      "@components",
+      "@/*",
+    ]
+  `);
+  expect(Object.values(result)).toMatchInlineSnapshot(`
+    [
+      [
+        "./src/utils",
+      ],
+      [
+        "./src/components",
+      ],
+      [
+        "./src/*",
+      ],
+    ]
+  `);
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 789dca217..6c00116a6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -732,8 +732,6 @@ importers:
         specifier: ^5.1.0
         version: 5.1.0
 
-  tests/integration/dts/bundle-false/alias/compile/express: {}
-
   tests/integration/dts/bundle-false/auto-extension: {}
 
   tests/integration/dts/bundle-false/basic: {}
@@ -924,8 +922,6 @@ importers:
         specifier: ^5.8.3
         version: 5.8.3
 
-  tests/integration/redirect/dts/compile/prebundle-pkg: {}
-
   tests/integration/redirect/js:
     devDependencies:
       '@types/lodash':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index c279a285c..35f6fddf9 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -5,6 +5,7 @@ packages:
   - 'tests/**'
   - 'examples/**'
   - '!**/compiled/**'
+  - '!**/compile/**'
   - '!**/dist-types/**'
 
 onlyBuiltDependencies:
diff --git a/tests/integration/dts/index.test.ts b/tests/integration/dts/index.test.ts
index 5c017611d..fe0592457 100644
--- a/tests/integration/dts/index.test.ts
+++ b/tests/integration/dts/index.test.ts
@@ -169,6 +169,28 @@ describe('dts when bundle: false', () => {
       );
     }
   });
+
+  test('alias', async () => {
+    const fixturePath = join(__dirname, 'bundle-false', 'alias');
+    const { contents } = await buildAndGetResults({
+      fixturePath,
+      type: 'dts',
+    });
+
+    expect(contents.esm).toMatchInlineSnapshot(`
+      {
+        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/esm/index.d.ts": "export {} from '../../compile/express';
+      ",
+      }
+    `);
+
+    expect(contents.cjs).toMatchInlineSnapshot(`
+      {
+        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/cjs/index.d.ts": "export {} from '../../compile/express';
+      ",
+      }
+    `);
+  });
 });
 
 describe('dts when bundle: true', () => {
diff --git a/website/docs/en/config/lib/dts.mdx b/website/docs/en/config/lib/dts.mdx
index 0ff28456d..6228da934 100644
--- a/website/docs/en/config/lib/dts.mdx
+++ b/website/docs/en/config/lib/dts.mdx
@@ -222,7 +222,7 @@ It follows the same logic as [lib.autoExtension](/config/lib/auto-extension), bu
 
 ### dts.alias
 
-- **Type:**` Record<string, string>`
+- **Type:** `Record<string, string>`
 - **Default:** `{}`
 
 Configure the path alias for declaration files.

From 183eee2d0349818381e8f23aaadbe3fd13ddbadd Mon Sep 17 00:00:00 2001
From: Timeless0911 <1604889533@qq.com>
Date: Tue, 29 Jul 2025 19:22:31 +0800
Subject: [PATCH 4/4] chore: update

---
 pnpm-lock.yaml                                           | 9 +--------
 .../alias/compile/{express => prebundle-pkg}/index.d.ts  | 0
 .../alias/compile/{express => prebundle-pkg}/index.js    | 0
 .../compile/{express => prebundle-pkg}/package.json      | 2 +-
 tests/integration/dts/bundle-false/alias/package.json    | 6 +-----
 tests/integration/dts/bundle-false/alias/rslib.config.ts | 4 ++--
 tests/integration/dts/bundle-false/alias/src/index.ts    | 2 +-
 tests/integration/dts/index.test.ts                      | 4 ++--
 8 files changed, 8 insertions(+), 19 deletions(-)
 rename tests/integration/dts/bundle-false/alias/compile/{express => prebundle-pkg}/index.d.ts (100%)
 rename tests/integration/dts/bundle-false/alias/compile/{express => prebundle-pkg}/index.js (100%)
 rename tests/integration/dts/bundle-false/alias/compile/{express => prebundle-pkg}/package.json (61%)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6c00116a6..849b73a1a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -723,14 +723,7 @@ importers:
 
   tests/integration/dts/bundle-false/abort-on-error: {}
 
-  tests/integration/dts/bundle-false/alias:
-    devDependencies:
-      '@types/express':
-        specifier: ^5.0.3
-        version: 5.0.3
-      express:
-        specifier: ^5.1.0
-        version: 5.1.0
+  tests/integration/dts/bundle-false/alias: {}
 
   tests/integration/dts/bundle-false/auto-extension: {}
 
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/index.d.ts b/tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/index.d.ts
similarity index 100%
rename from tests/integration/dts/bundle-false/alias/compile/express/index.d.ts
rename to tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/index.d.ts
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/index.js b/tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/index.js
similarity index 100%
rename from tests/integration/dts/bundle-false/alias/compile/express/index.js
rename to tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/index.js
diff --git a/tests/integration/dts/bundle-false/alias/compile/express/package.json b/tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/package.json
similarity index 61%
rename from tests/integration/dts/bundle-false/alias/compile/express/package.json
rename to tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/package.json
index d8ebb18eb..5126af028 100644
--- a/tests/integration/dts/bundle-false/alias/compile/express/package.json
+++ b/tests/integration/dts/bundle-false/alias/compile/prebundle-pkg/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "express",
+  "name": "prebundle-pkg",
   "version": "0.0.0",
   "private": true
 }
diff --git a/tests/integration/dts/bundle-false/alias/package.json b/tests/integration/dts/bundle-false/alias/package.json
index 316782849..9905c5a60 100644
--- a/tests/integration/dts/bundle-false/alias/package.json
+++ b/tests/integration/dts/bundle-false/alias/package.json
@@ -2,9 +2,5 @@
   "name": "dts-bundle-false-alias-test",
   "version": "1.0.0",
   "private": true,
-  "type": "module",
-  "devDependencies": {
-    "@types/express": "^5.0.3",
-    "express": "^5.1.0"
-  }
+  "type": "module"
 }
diff --git a/tests/integration/dts/bundle-false/alias/rslib.config.ts b/tests/integration/dts/bundle-false/alias/rslib.config.ts
index 5d34269ed..dd778482e 100644
--- a/tests/integration/dts/bundle-false/alias/rslib.config.ts
+++ b/tests/integration/dts/bundle-false/alias/rslib.config.ts
@@ -7,7 +7,7 @@ export default defineConfig({
       dts: {
         bundle: false,
         alias: {
-          express: './compile/express',
+          'prebundle-pkg': './compile/prebundle-pkg',
         },
       },
     }),
@@ -15,7 +15,7 @@ export default defineConfig({
       dts: {
         bundle: false,
         alias: {
-          express: './compile/express',
+          'prebundle-pkg': './compile/prebundle-pkg',
         },
       },
     }),
diff --git a/tests/integration/dts/bundle-false/alias/src/index.ts b/tests/integration/dts/bundle-false/alias/src/index.ts
index 77525a3a9..8fc482265 100644
--- a/tests/integration/dts/bundle-false/alias/src/index.ts
+++ b/tests/integration/dts/bundle-false/alias/src/index.ts
@@ -1 +1 @@
-export {} from 'express';
+export {} from 'prebundle-pkg';
diff --git a/tests/integration/dts/index.test.ts b/tests/integration/dts/index.test.ts
index fe0592457..ebb973eaa 100644
--- a/tests/integration/dts/index.test.ts
+++ b/tests/integration/dts/index.test.ts
@@ -179,14 +179,14 @@ describe('dts when bundle: false', () => {
 
     expect(contents.esm).toMatchInlineSnapshot(`
       {
-        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/esm/index.d.ts": "export {} from '../../compile/express';
+        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/esm/index.d.ts": "export {} from '../../compile/prebundle-pkg';
       ",
       }
     `);
 
     expect(contents.cjs).toMatchInlineSnapshot(`
       {
-        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/cjs/index.d.ts": "export {} from '../../compile/express';
+        "<ROOT>/tests/integration/dts/bundle-false/alias/dist/cjs/index.d.ts": "export {} from '../../compile/prebundle-pkg';
       ",
       }
     `);