Module resolution: "nodenext" fails to follow imports in `.d.ts` files of dependency packages that are `"type": "module"`

[Harris-Miller]

Demo Repo

https://github.com/Harris-Miller/moduleResolutionIssue

Which of the following problems are you reporting?

The module specifier resolves at runtime, but not at build time

Demonstrate the defect described above with a code sample.

https://github.com/Harris-Miller/moduleResolutionIssue/blob/main/app/src/fib.ts#L1

import { add, append } from 'test-lib';

Produces error TS2305: Module '"test-lib"' has no exported member 'add'.

add comes from a local dependency; the declaration file can be found in dist/math.d.ts
If you search for the word "math" in my attached tsc --traceResolution you'll find

Loading module as file / folder, candidate module location '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math', target file types: TypeScript, JavaScript, Declaration, JSON.
Directory '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math' does not exist, skipping all lookups in it.
======== Module name './math' was not resolved. ========

Import to the failed resolution is that libs/package.json is configured as "type": "module"
It appears that when using "moduleResolution": "nodenext", when resolving files of dependencies, it's applying resolution for each depent package to that package's package.json#type value. That makes sense for runtime code, but breaks for declaration .d.ts files, which can never be built with important statements containing file extensions

Run tsc --showConfig and paste its output here

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "moduleResolution": "nodenext",
        "types": [],
        "sourceMap": false,
        "declaration": false,
        "declarationMap": false,
        "noUncheckedIndexedAccess": false,
        "exactOptionalPropertyTypes": true,
        "strict": true,
        "jsx": "react-jsx",
        "verbatimModuleSyntax": false,
        "isolatedModules": true,
        "noUncheckedSideEffectImports": true,
        "moduleDetection": "force",
        "skipLibCheck": true,
        "target": "esnext",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "resolvePackageJsonExports": true,
        "resolvePackageJsonImports": true,
        "resolveJsonModule": true,
        "preserveConstEnums": true,
        "useDefineForClassFields": true,
        "noImplicitAny": true,
        "noImplicitThis": true,
        "strictNullChecks": true,
        "strictFunctionTypes": true,
        "strictBindCallApply": true,
        "strictPropertyInitialization": true,
        "strictBuiltinIteratorReturn": true,
        "alwaysStrict": true,
        "useUnknownInCatchVariables": true
    },
    "files": [
        "./src/fib.ts",
        "./src/main.ts"
    ],
    "exclude": [
        "/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/dist"
    ]
}

Run tsc --traceResolution and paste its output here

File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/package.json' does not exist.
Found 'package.json' at '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/package.json'.
======== Resolving module 'react/jsx-runtime' from '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/fib.ts'. ========
Explicitly specified module resolution kind: 'NodeNext'.
Resolving in CJS mode with conditions 'require', 'types', 'node'.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/package.json' does not exist according to earlier cached lookups.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/package.json' exists according to earlier cached lookups.

...

======== Resolving module 'test-lib' from '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/fib.ts'. ========
Explicitly specified module resolution kind: 'NodeNext'.
Resolving in CJS mode with conditions 'require', 'types', 'node'.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/package.json' does not exist according to earlier cached lookups.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/package.json' exists according to earlier cached lookups.
Loading module 'test-lib' from 'node_modules' folder, target file types: TypeScript, JavaScript, Declaration, JSON.
Searching all ancestor node_modules directories for preferred extensions: TypeScript, Declaration.
Directory '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/node_modules' does not exist, skipping all lookups in it.
Found 'package.json' at '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/node_modules/test-lib/package.json'.
Entering conditional exports.
Matched 'exports' condition 'types'.
Using 'exports' subpath '.' with target './dist/index.d.ts'.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/node_modules/test-lib/dist/index.d.ts' exists - use it as a name resolution result.
'package.json' does not have a 'peerDependencies' field.
Resolved under condition 'types'.
Exiting conditional exports.
Resolving real path for '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/node_modules/test-lib/dist/index.d.ts', result '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/index.d.ts'.
======== Module name 'test-lib' was successfully resolved to '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/index.d.ts' with Package ID 'test-lib/dist/index.d.ts@1.0.0'. ========
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/package.json' does not exist.
Found 'package.json' at '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/package.json'.
======== Resolving module './math' from '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/index.d.ts'. ========
Explicitly specified module resolution kind: 'NodeNext'.
Resolving in ESM mode with conditions 'import', 'types', 'node'.
Loading module as file / folder, candidate module location '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math', target file types: TypeScript, JavaScript, Declaration, JSON.
Directory '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math' does not exist, skipping all lookups in it.
======== Module name './math' was not resolved. ========
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/src/package.json' does not exist according to earlier cached lookups.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/app/package.json' exists according to earlier cached lookups.

...

src/fib.ts(1,10): error TS2305: Module '"test-lib"' has no exported member 'add'.

Paste the package.json of the importing module, if it exists

{
  "name": "test-app",
  "private": true,
  "version": "1.0.0",
  "description": "",
  "main": "dist/main.js",
  "scripts": {
    "build": "tsc",
    "start": "node ./dist/main.js",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "test-lib": "file://../lib"
  },
  "devDependencies": {
    "@types/node": "^22.18.6",
    "tslib": "^2.8.1",
    "typescript": "^5.9.2"
  }
}

Paste the package.json of the target module, if it exists

{
  "name": "test-lib",
  "type": "module",
  "version": "1.0.0",
  "description": "",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "rollup -c",
    "typecheck": "tsc --noEmit"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@rollup/plugin-typescript": "^12.1.4",
    "@types/node": "^22.18.6",
    "rollup": "^4.52.2",
    "tslib": "^2.8.1",
    "typescript": "^5.9.2"
  }
}

Any other comments can go here

I removed the unimportant bits in my pasted tsc --traceResolition for brevity

Typescript doesn't have a problem resolving "types": "./dist/index.d.ts" since there is an extension there, the problem is for then that file imports others without extensions, which is always

[RyanCavanaugh]

This is a misconfiguration on a few levels (it seems like app didn't mean to be CJS, but is?), but the core problem here is that you've set moduleResolution to bundler in lib and written an ESM module that doesn't use file extensions, then used a bundler (rollup) that didn't produce a .d.ts file that actually works under ESM module resolution rules.

TL;DR you should change

export * from './math';

in index.ts to

export * from './math.js';

Running tsc --skipLibCheck false in app would have shown you the problme.

[Harris-Miller]

@RyanCavanaugh Thank you for your reply.

it seems like app didn't mean to be CJS, but is?

That's intentional. tl;dr is:

• app has been around for a while, target is CJS, built with tsc, module: "nodenext"
• lib produces both ESM and CJS code, package.json#exports configured as you'd expect
  • assume this lib is browser/node runtime agnostic

In my re-world scenario, we created a new lib in our stack that we made "type": "modules" so all config files (eslint, jest, rollup) and scripting files can be written ESM, and so we didn't have to use .mjs extensions. The rest of the build process is the same as the others with rollup. That new lib was only used in our webapp for 6months, and only got pulled into one of our backend services this week. This is how we came across the problem I discribed

---

Per node's docs

The "type" field defines the module format that Node.js uses for all .js files that have that package.json file as their nearest parent.
Files ending with .js are loaded as ES modules when the nearest parent package.json file contains a top-level field "type" with a value of "module".

This makes sense, and I understand how "type": "module". Though I was surprised to learn that my current rollup config in lib breaks in Node18 (Node20+ works with a Warning that it failed to parse CJS and reparsed as ESM). I was under the impression that it wouldn't matter if my libe was"type": "commonjs" and dist/*.js extensions were ESM because I'm directing node resolver to go to that file via import condition in package.json#exports, which I thought implied ESM the same as .mjs does

This is fixable by having rollup write .mjs extensions for my ESM output, just as I'm already doing .cjs for CJS output.

the core problem here is that you've set moduleResolution to bundler in lib and written an ESM module that doesn't use file extensions, then used a bundler (rollup) that didn't produce a .d.ts file that actually works under ESM module resolution rules.

My rollup writes both ESM and CJS code to dist, and after applying the above change, adds the correct file extensions as part of that process. So my runtime code works for the consuming app's package.json "type" is set to. Lib being set to "types": "module" has no bearing on the consumer.

Therefore, it should have no bearing on how TypeScript follows import statements in .d.ts files. Using rollup to bundle up the lib code and produce d.ts files (regardless if via rollup or with a separate tsc --emitDeclarationOnly task) is extremely common in the ecosystem. I should not have to be required to overhaul my src code, adding extensions and updating folder imports to add /index.js because of how my downstream consumer has their "moduleResolution" set

Should "moduleResolution": "nodenext" fail if in repo code is ESM and my lib is ESM without extensions (eg tsc --module esnext --moduleResolution bundler)... yes. Yes, it should. It's not NodeJS ESM compliant. But Declaration files... those are a completely separate things. They live outside of NodeJS's resolution algorithms, and therefor should not be dictated by it

---

And if you don't buy my argument stand-alone, consider the following...

Let's say in my lib I update all my src typescript code with correct extensions and folder imports get /index.js added. My declaration files now have './math.js';, satisfying "nodenext" + "type": "module" requirements

But there is no math.js. There is a math.cjs and a math.mjs. Then what about if I remove "preserveModules" from the rollup config. Then there is no javascript math file at all in dist! Only the declaration file representing the original source. And that's my point. They represent the types of the source code, NOT the built javascript code.

I did those changes and rename tsc --traceModules and this is what I got for ./math.js

======== Resolving module './math.js' from '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/index.d.ts'. ========
Explicitly specified module resolution kind: 'NodeNext'.
Resolving in ESM mode with conditions 'import', 'types', 'node'.
Loading module as file / folder, candidate module location '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.js', target file types: TypeScript, JavaScript, Declaration, JSON.
File name '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.js' has a '.js' extension - stripping it.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.ts' does not exist.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.tsx' does not exist.
File '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.d.ts' exists - use it as a name resolution result.
======== Module name './math.js' was successfully resolved to '/Users/hmiller/Projects/harris-miller/moduleResolutionIssue/lib/dist/math.d.ts'. ========

The resolver strips the .js extension and tries to resolve for .ts, .tsx, and .d.ts. If it's going to strip the extension, why shouldn't it also try to resolve for those same file types if ./math is not first resolved as a directory? It even says "Loading module as file / folder". If math was a directory and I have an index.ts and add.ts files it in, my ./math import resolves to math/index.ts. Which again, only represents the original source files. NOT my built code that got bundled into a single file

Declaration file resolution should not be limited in this way by "types": "modules" in any package.json. Full stop

And if the Typescript leaders believe it should, than allowImportingTsExtensions should be removed immediately

This flag is only allowed when --noEmit or --emitDeclarationOnly is enabled, since these import paths would not be resolvable at runtime in JavaScript output files. The expectation here is that your resolver (e.g. your bundler, a runtime, or some other tool) is going to make these imports between .ts files work.

That's needs to be a two way street or nothing at all

Thank you

[RyanCavanaugh]

But Declaration files... those are a completely separate things. They live outside of NodeJS's resolution algorithms, and therefor should not be dictated by it [...] The resolver strips the .js extension and tries to resolve for .ts, .tsx, and .d.ts. If it's going to strip the extension, why shouldn't it also try to resolve for those same file types if ./math is not first resolved as a directory?

Having "math" fall back to "math.js" creates a versioning hazard where adding a math export map causes module resolution to change where lands. And there's no way to end up in this situation without a misconfiguration in the first place.

You're producing an incorrect declaration file here by configuring TypeScript in a way that doesn't reflect reality.

But there is no math.js. There is a math.cjs and a math.mjs

You can write from "./math.mjs" too (given a math.mts input), that's totally fine and will work.

Then what about if I remove "preserveModules" from the rollup config.

We're not here to dictate rollup's behavior, I can't speak to that.

It seems like you might be misapprehending something -- TypeScript is intentionally not a tool to do CJS-ESM dual emit; see #54593

And if the Typescript leaders believe it should, than allowImportingTsExtensions should be removed immediately [...] That's needs to be a two way street or nothing at all

It's not incumbent on us to remove it if people use it in a way that isn't in line with how it works. You're free to not use it.

[Harris-Miller]

You're producing an incorrect declaration file here by configuring TypeScript in a way that doesn't reflect reality.

Can you expand on "reflect reality" for me? please and thank you

[RyanCavanaugh]

If you're using a bundler, then the bundler needs to be (correctly) rewriting import paths on emit

[Harris-Miller]

If you're using a bundler, then the bundler needs to be (correctly) rewriting import paths on emit

It does. rollup with "preserveModules" (keeps original src code dir structure) for example, will rewrite ts './path/to/dir'; to './path/to/dir/index.js' without any special configuration.

[Harris-Miller]

You're producing an incorrect declaration file here by configuring TypeScript in a way that doesn't reflect reality.

That at minimum tsc should supply a way for me to produce a correct declaration file with "moduleResolution": "bundler" for TS code that omits extensions and imports directories.

While there are many options to transpile TS to JS, there is only one to generate declaration files. If my bundler can produce files that work with the setup I have at runtime, so shouldtsc be able to generate declaration files to match

[RyanCavanaugh]

Only the bundler knows what it's doing with various source files, paths, etc, and it needs to be able to handle declaration files too in an analogous way.

Otherwise you end up in a situation where e.g. you have lib/subDir/foo.ts which produces dist/subDir/foo.d.ts, but the bundler folded foo.ts into a single file, and so TS would think that import * from "yourLib/subDir/foo.js" was a valid sub-import because it saw the .d.ts on disk.

[Harris-Miller]

and so TS would think that import * from "yourLib/subDir/foo.js" was a valid sub-import because it saw the .d.ts on disk.

But that's true today as well. I can add file extensions in my ts code, configure with type: "module" and nodenext, have rollup bundle everything into dist/index.js, and tsc --emitDeclarationOnly that will produce a dist/index.d.ts that contains:

import { add } from './math.js';

[RyanCavanaugh]

Right, which is why a bundler needs to do the same transform to the .d.ts files (inline, change file extension/paths, etc) that it does to the .ts files. That's exactly what I'm getting at -- TypeScript doesn't know your bundler config, can't possibly represent the entire universe of bundler behavior anyway, and can only emit for the sake of the bundler so that it (the bundler) can produce a .d.ts that represents the shape of the JS module that it ended up emitting.

[Harris-Miller]

Look, the bottom line is the resolution behavior of nodenext fails for libraries in this circumstance. It is more than common to build declarations with tsc but the runtime code with other tool for libraries. IMHO tsc should be able to either a) resolve imports in .d.ts files regardless of how "types" is set in a dependency, or provide a way to generate types that will resolve correctly given the current resolution rules

It feels like an artificial limitation that typescript not be able to produce types to support this in one way or another. And I'm not saying there shouldn't be limitations; there absolutely should be. Nor should it be the responsibility of typescript to represent the entire universe of bundler behaviors. It's on developers to responsibly use the bundlers produce so that runtime behavior matches what what typescript can produce for types for libs that get used downstream. And therefore, typescript should not have limiting options around that concerning runtime options such as "types": "modules".

Though I guess the real takeaway from all this just don't use "types": "modules" in your libraries (sigh). Guess I'm just going with.mjs files for everything moving forward

TypeScript doesn't know your bundler config

Let's be honest, TypeScript doesn't know its own config either when it comes to producing declarations and resolutions (looking at you "paths")

[Harris-Miller]

@RyanCavanaugh thank you for your time and attention. It's appreciated