feat(dts): add cjsReexport option to eliminate dual module type hazard

Author: mandarini

src/build.ts

@@ -1,3 +1,5 @@
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
 import { bold, green } from 'ansis'
 import { clearRequireCache } from 'import-without-cache'
 import {
@@ -290,16 +292,18 @@ async function buildSingle(
 
     const configs: BuildOptions[] = [buildOptions]
     if (format === 'cjs' && dts) {
-      configs.push(
-        await getBuildOptions(
-          config,
-          format,
-          configFiles,
-          bundle,
-          true,
-          isDualFormat,
-        ),
-      )
+      if (!isDualFormat || !dts.cjsReexport) {
+        configs.push(
+          await getBuildOptions(
+            config,
+            format,
+            configFiles,
+            bundle,
+            true,
+            isDualFormat,
+          ),
+        )
+      }
     }
 
     return configs
@@ -308,6 +312,11 @@ async function buildSingle(
   async function postBuild() {
     await copy(config)
     await buildExe(config, chunks)
+
+    if (format === 'cjs' && dts && dts.cjsReexport && isDualFormat) {
+      await writeCjsDtsReexports(chunks, outDir, config.write !== false)
+    }
+
     if (!hasBuilt) {
       await done(bundle)
     }
@@ -319,3 +328,27 @@ async function buildSingle(
     ab = executeOnSuccess(config)
   }
 }
+
+async function writeCjsDtsReexports(
+  chunks: RolldownChunk[],
+  outDir: string,
+  write: boolean,
+): Promise<void> {
+  for (const chunk of chunks) {
+    if (chunk.type !== 'chunk') continue
+
+    // Match CJS JS output files: .cjs (fixed extension) or .js (non-fixed)
+    const match = chunk.fileName.match(/^(.*)\.(cjs|js)$/)
+    if (!match) continue
+
+    const baseName = match[1]
+    const dCtsName =
+      match[2] === 'cjs' ? `${baseName}.d.cts` : `${baseName}.d.ts`
+    const dMtsBasename = path.basename(`${baseName}.d.mts`)
+    const content = `export * from './${dMtsBasename}'\n`
+
+    if (write) {
+      await writeFile(path.join(outDir, dCtsName), content)
+    }
+  }
+}

src/config/types.ts

@@ -44,7 +44,25 @@ import type {
   OutputOptions,
   TreeshakingOptions,
 } from 'rolldown'
-import type { Options as DtsOptions } from 'rolldown-plugin-dts'
+import type { Options as RolldownPluginDtsOptions } from 'rolldown-plugin-dts'
+
+export interface DtsOptions extends RolldownPluginDtsOptions {
+  /**
+   * When building dual ESM+CJS formats, generate a `.d.cts` re-export stub
+   * instead of running a full second TypeScript compilation pass.
+   *
+   * The stub re-exports everything from the corresponding `.d.mts` file,
+   * ensuring CJS and ESM consumers share the same type declarations. This
+   * eliminates the TypeScript "dual module hazard" where separate `.d.cts`
+   * and `.d.mts` declarations cause `TS2352` ("neither type sufficiently
+   * overlaps") errors when casting between types derived from the same class.
+   *
+   * Only applies when building both `esm` and `cjs` formats simultaneously.
+   *
+   * @default false
+   */
+  cjsReexport?: boolean
+}
 import type { Options as UnusedOptions } from 'unplugin-unused'
 
 export type Sourcemap = boolean | 'inline' | 'hidden'
@@ -83,7 +101,6 @@ export type {
   CopyOptionsFn,
   DepsConfig,
   DevtoolsOptions,
-  DtsOptions,
   ExeOptions,
   ExportsOptions,
   NoExternalFn,

src/features/rolldown.ts

@@ -117,9 +117,10 @@ async function resolveInputOptions(
 
   if (dts) {
     const { dts: dtsPlugin } = await import('rolldown-plugin-dts')
+    const { cjsReexport: _, ...dtsPluginOptions } = dts
     const options: DtsOptions = {
       tsconfig,
-      ...dts,
+      ...dtsPluginOptions,
     }
 
     if (format === 'es') {

tests/__snapshots__/cjs-dts-reexport.snap.md

@@ -0,0 +1,40 @@
+## index.cjs
+
+```cjs
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region index.ts
+function hello() {
+	console.log("Hello!");
+}
+//#endregion
+exports.hello = hello;
+
+```
+
+## index.d.cts
+
+```cts
+export * from './index.d.mts'
+
+```
+
+## index.d.mts
+
+```mts
+//#region index.d.ts
+declare function hello(): void;
+//#endregion
+export { hello };
+```
+
+## index.mjs
+
+```mjs
+//#region index.ts
+function hello() {
+	console.log("Hello!");
+}
+//#endregion
+export { hello };
+
+```

tests/e2e.test.ts

@@ -98,6 +98,22 @@ test('cjs default', async (context) => {
   })
 })
 
+test('cjs dts reexport', async (context) => {
+  const files = {
+    'index.ts': `export function hello(): void {
+      console.log('Hello!')
+    }`,
+  }
+  await testBuild({
+    context,
+    files,
+    options: {
+      format: ['esm', 'cjs'],
+      dts: { cjsReexport: true },
+    },
+  })
+})
+
 test('fixed extension', async (context) => {
   const files = {
     'index.ts': `export default 10`,