fix: warn for CommonJS dts inputs

sxzz · sxzz · commit 78288dbca0d9 · 2026-05-15T22:09:16.000+09:00
Closes #240
diff --git a/README.md b/README.md
@@ -109,6 +109,8 @@ Determines how the default export is emitted.
 If set to `true`, and you are only exporting a single item using `export default ...`,
 the output will use `export = ...` instead of the standard ES module syntax.
 This is useful for compatibility with CommonJS.
+This option only controls the output format and does not enable support for
+CommonJS-style `.d.ts` input.
 
 #### `sideEffects`
 
@@ -236,6 +238,11 @@ However, this functionality is limited to ESM output format. Consequently,
 and its corresponding type definition files (`.d.cts`).
 In such cases, the `emitDtsOnly` option can be particularly helpful.
 
+The plugin expects ESM-style `.d.ts` input. CommonJS-style declaration syntax
+such as `export =` or `import x = require("x")` will produce a warning and is
+not guaranteed to bundle correctly. If this syntax comes from a dependency in
+`node_modules`, mark that dependency as external in your Rolldown config.
+
 ## Credits
 
 The project is inspired by [rollup-plugin-dts](https://github.com/Swatinem/rollup-plugin-dts)
diff --git a/src/fake-js.ts b/src/fake-js.ts
@@ -13,6 +13,7 @@ import {
   filename_js_to_dts,
   RE_DTS,
   RE_DTS_MAP,
+  RE_NODE_MODULES,
   replaceTemplateName,
   resolveTemplateFn,
 } from './filename.ts'
@@ -70,6 +71,7 @@ export function createFakeJsPlugin({
   const declarationMap = new Map<number /* declaration id */, DeclarationInfo>()
   const commentsMap = new Map<string /* filename */, t.Comment[]>()
   const typeOnlyMap = new Map<string /* filename */, string[]>()
+  const warnedCjsDtsInputs = new Set<string>()
 
   return {
     name: 'rolldown-plugin-dts:fake-js',
@@ -161,6 +163,15 @@ export function createFakeJsPlugin({
     const typeOnlyIds: string[] = []
     const identifierMap: Record<string, number> = Object.create(null)
 
+    if (!warnedCjsDtsInputs.has(id) && program.body.some(isCjsDtsInputSyntax)) {
+      warnedCjsDtsInputs.add(id)
+      this.warn(
+        RE_NODE_MODULES.test(id)
+          ? `${id} uses CommonJS dts syntax. CommonJS dts modules cannot be reliably bundled by rolldown-plugin-dts. Please mark this module as external in your Rolldown config.`
+          : `${id} uses CommonJS dts syntax. rolldown-plugin-dts does not support reliably bundling CommonJS dts input.`,
+      )
+    }
+
     if (comments) {
       const directives = collectReferenceDirectives(comments)
       commentsMap.set(id, directives)
@@ -822,6 +833,14 @@ function collectReferenceDirectives(comment: t.Comment[], negative = false) {
   return comment.filter((c) => REFERENCE_RE.test(c.value) !== negative)
 }
 
+function isCjsDtsInputSyntax(node: t.Statement): boolean {
+  return (
+    node.type === 'TSExportAssignment' ||
+    (node.type === 'TSImportEqualsDeclaration' &&
+      node.moduleReference.type === 'TSExternalModuleReference')
+  )
+}
+
 //#region Runtime binding variable
 
 /**
diff --git a/src/options.ts b/src/options.ts
@@ -89,6 +89,8 @@ export interface GeneralOptions {
    * If set to `true`, and you are only exporting a single item using `export default ...`,
    * the output will use `export = ...` instead of the standard ES module syntax.
    * This is useful for compatibility with CommonJS.
+   * This only controls the output format and does not enable support for
+   * CommonJS-style `.d.ts` input.
    */
   cjsDefault?: boolean
 
diff --git a/tests/index.test.ts b/tests/index.test.ts
@@ -1,6 +1,8 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { rolldownBuild } from '@sxzz/test-utils'
+import { normalizePath, rolldownBuild } from '@sxzz/test-utils'
 import { describe, expect, test } from 'vitest'
 import { dts } from '../src/index.ts'
 import { getTsgoPathFromNodeModules } from '../src/tsgo.ts'
@@ -157,6 +159,81 @@ describe('dts input', () => {
     expect(snapshot).toMatchSnapshot()
   })
 
+  test('warns for CommonJS dts input syntax', async () => {
+    const warnings: string[] = []
+
+    await rolldownBuild(
+      [
+        path.resolve(
+          dirname,
+          'rollup-plugin-dts/issue-89-import-equals/index.d.ts',
+        ),
+      ],
+      [dts({ dtsInput: true })],
+      {
+        onwarn(warning) {
+          warnings.push(warning.message)
+        },
+      },
+    )
+
+    expect(warnings).toHaveLength(2)
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('index.d.ts uses CommonJS dts syntax'),
+        expect.stringContaining('bar.d.ts uses CommonJS dts syntax'),
+      ]),
+    )
+    expect(warnings.join('\n')).toContain(
+      'rolldown-plugin-dts does not support reliably bundling CommonJS dts input',
+    )
+  })
+
+  test('warns to externalize CommonJS dts dependencies', async () => {
+    const root = await mkdtemp(path.join(tmpdir(), 'rolldown-plugin-dts-'))
+    const dep = path.join(root, 'node_modules/cjs-dts-dep')
+    const warnings: string[] = []
+
+    try {
+      await mkdir(dep, { recursive: true })
+      await Promise.all([
+        writeFile(
+          path.join(root, 'index.d.ts'),
+          `export interface Wrapped {\n  value: import("cjs-dts-dep").Value\n}\n`,
+        ),
+        writeFile(
+          path.join(dep, 'package.json'),
+          `{"name":"cjs-dts-dep","types":"index.d.ts"}`,
+        ),
+        writeFile(
+          path.join(dep, 'index.d.ts'),
+          `declare namespace CjsDtsDep {\n  export interface Value {\n    foo: string\n  }\n}\nexport = CjsDtsDep\n`,
+        ),
+      ])
+
+      await rolldownBuild(
+        [path.join(root, 'index.d.ts')],
+        [dts({ dtsInput: true })],
+        {
+          cwd: root,
+          onwarn(warning) {
+            warnings.push(warning.message)
+          },
+        },
+      )
+    } finally {
+      await rm(root, { force: true, recursive: true })
+    }
+
+    const cjsWarning =
+      warnings.find((warning) =>
+        normalizePath(warning).includes('node_modules/cjs-dts-dep/index.d.ts'),
+      ) ?? ''
+
+    expect(cjsWarning).toContain('uses CommonJS dts syntax')
+    expect(cjsWarning).toContain('Please mark this module as external')
+  })
+
   test('input object', async () => {
     const { snapshot, chunks } = await rolldownBuild(
       { index: path.resolve(dirname, 'fixtures/dts-input.d.ts') },
