The rule from the TypeScript handbook: every declaration file represents exactly one JavaScript file, and its module format must match that file. tsc decides a declaration file's format the same way Node decides a JavaScript file's: .d.mts is ESM, .d.cts is CommonJS, and .d.ts follows the nearest package.json "type".
A dual package ships index.mjs for import and index.cjs for require. The types must split the same way:
- Per-condition types. Nest
typesinside each branch:"import": { "types": "./index.d.mts", "default": "./index.mjs" }and the same forrequirewith.d.cts.typesgoes first in each object; Node's docs say so and conditions match in key order. - Or let extension substitution do it. For a target
./index.mjs,tsclooks forindex.mts, thenindex.d.mts, so files sitting next to each other need notypeskey. The same works with twodist/folders whose ownpackage.jsonsets"type".
The common bug is one .d.ts for both builds. Without "type": "module" it is read as CommonJS, so an ESM consumer's default import gets module.exports and the types claim the function sits on .default. That is masquerading as CJS. With "type": "module" the opposite (masquerading as ESM) misleads require users.
To produce the files, compile twice (one output per format), because a single tsc run emits one format per file. The handbook warns that any dual-emit setup checks only one output, so test both builds before publishing. arethetypeswrong (npx @arethetypeswrong/cli) is a tool that reports these mismatches per resolution mode.
Since require() can load synchronous ES modules (unflagged in Node 22.12 and 20.19), shipping ESM only is often the simpler answer.