TS2307 and TS2835: Cannot Find Module Under moduleResolution NodeNext
NodeNext models Node's real resolution, so .js belongs in the source import and exports maps decide what exists. Why bundler resolution hides both errors.

Introduction & Quick Summary
Symptom. After setting "module": "nodenext" (or upgrading a tsconfig that came from a template), tsc fills the terminal with error TS2307: Cannot find module './lib/utils' or its corresponding type declarations. and, next to it, error TS2835: Relative import paths need explicit file extensions in ECMAScript imports when '--moduleResolution' is 'node16' or 'nodenext'. Did you mean './lib/utils.js'? Runtime was fine before; nothing in the code changed.
Cause. node16/nodenext tells TypeScript to model Node.js's real resolution algorithm rather than a bundler's. In that model, an ESM relative import must name a file that exists after compilation: there is no extension-less lookup and no directory index.js fallback. A package that publishes an exports map is also resolved only through that map, so a subpath or a types condition missing from it produces TS2307 even though the JavaScript works at runtime. Under moduleResolution: "bundler" — the tsconfig a Next.js or Vite app ships — both errors disappear because the bundler does that guessing for you.
Fix. Write ./lib/utils.js in the TypeScript source; the emitted file and its specifier match. Add "types" as the first condition in every exports entry you publish, keep "type": "module" consistent with the file extensions you emit, and use paths for aliases that Node cannot see. Move to "moduleResolution": "bundler" only when a bundler really owns the runtime.
Core Mechanics, Signatures & Reproducible Setup
One project, three resolutions, three different answers for the same import:
// Node ESM app compiled with tsc — what errors here is real
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"target": "es2023",
"outDir": "dist",
"rootDir": "src",
"strict": true,
"verbatimModuleSyntax": true
},
"include": ["src"]
}// src/index.ts
import { slugify } from './lib/utils'; // TS2835 + TS2307 under nodenext
import { slugify } from './lib/utils.js'; // correct: .js in the source, resolves to utils.tsWith "type": "module" in package.json, dist/index.js is ESM and Node requires the .js suffix at runtime too, so the compiler error is a preview of a runtime ERR_MODULE_NOT_FOUND.
A package you publish needs the conditions in the right order; TypeScript reads the first match, so types must precede import and require:
{
"name": "acme-utils",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js",
"require": "./dist/index.cjs"
},
"./slug": {
"types": "./dist/slug.d.ts",
"default": "./dist/slug.js"
}
},
"main": "./dist/index.cjs",
"types": "./dist/index.d.ts"
}If a consumer still gets TS2307 for acme-utils/slug, the subpath is absent from exports; Node's exports map is exhaustive and hides everything not listed. If the error is Could not find a declaration file for module 'acme-utils', the types condition is missing or points at a file that does not exist after build.
Key Comparison Table
moduleResolution | Extension required | Directory index | exports map | Use when |
|---|---|---|---|---|
node10 (legacy node) | No | Yes | Ignored | Old CJS projects only |
node16 / nodenext | Yes, in ESM files | No | Enforced | Node apps, libraries, CLIs |
bundler | No | Yes | Enforced | Next.js, Vite, webpack |
classic | No | No | Ignored | Do not use |
| Error | Real cause | Fix |
|---|---|---|
| TS2835 | Extensionless relative import in ESM | Add .js |
| TS2307 on a relative path | File missing, or .jsx/.mts mismatch | Fix the path or the extension |
| TS2307 on a package | Missing exports subpath or types | Add both to the package |
| TS7016 | Package has no bundled types | npm i -D @types/… or a local declaration |
| TS1479 | Importing ESM from CJS output | Use await import() or dual publish |
| TS5097 | .ts extension in import | Enable allowImportingTsExtensions with noEmit |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. Adding .js feels wrong but is correct
The specifier must be the path after compilation. ./utils.ts is not what Node loads; ./utils.js is. TypeScript maps .js back to .ts for type information, so editors and go-to-definition keep working.
// src/db/client.ts
import { pool } from '../lib/pool.js'; // resolves src/lib/pool.ts, emits dist/lib/pool.jsDo not rewrite these during a build step; post-processing import specifiers breaks source maps and the tsc --build incremental graph.
2. Directory imports that used to work
import { x } from './lib' relied on index.ts. Under nodenext write ./lib/index.js, and while you are there check the runtime: Node has never resolved a directory in ESM.
import { x } from './lib/index.js'; // explicit file, no directory fallback3. Aliases from a bundler tsconfig
@/components/Button works in Next.js because its tsconfig sets paths and its bundler resolves them. A Node service that copies the same paths block compiles, then fails at runtime because Node knows nothing about aliases.
{
"compilerOptions": {
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
}
}If a plain Node process must run the output, either emit relative specifiers or resolve aliases at runtime; a tsc-only fix is tsc-alias in the build script (tsc && tsc-alias), which rewrites the emitted imports.
4. .mts and .cts files
Extensions carry their own module format regardless of "type". An import '../config.mjs' from TypeScript needs a matching config.mts source and produces config.mjs:
// src/loader.mts -> dist/loader.mjs (always ESM)
import { load } from './config.mjs';The declaration file for config.mts is config.d.mts. Mixing .d.ts with .mts makes the types invisible to nodenext consumers, which shows up as TS2307 only in the consumer project.
5. verbatimModuleSyntax catches the next failure early
With verbatimModuleSyntax: true, import { type Foo } and import type are preserved or erased exactly as written, and a value import that is only used as a type becomes an error. That is what you want in a library: it guarantees the emitted specifiers match the source.
import type { Config } from './config.js'; // erased
import { createServer } from './server.js'; // kept6. Tests and ts-node under nodenext
ts-node uses the CommonJS loader by default, so a project that compiles cleanly still throws ERR_REQUIRE_ESM or Unknown file extension ".ts". Use the ESM loader, or replace the runner:
node --loader ts-node/esm src/index.ts
# or, simpler and faster
npx tsx src/index.tstsx and vitest both resolve .js specifiers back to .ts sources, so the same imports work in tests without a second tsconfig.
Common Compilation/Runtime Mistakes & Version Gotchas
moduleResolution: "bundler"withmodule: "commonjs". Invalid combination; TypeScript requiresmoduleto beesnext,preserveor similar. The error message names the pair, not the app's real problem."type": "module"plus.jsfiles that are CJS. Every.jsbecomes ESM andrequire()inside them fails. Rename to.cjsor convert.exportsbreaking deep imports. Addingexportshidesacme-utils/dist/internal.jsthat consumers imported directly. Add explicit subpaths before publishing a minor release.typesafterimportinexports. Condition order is significant: withimportfirst, TypeScript may resolve the JavaScript file and then fail to find types for it (TS7016 in the consumer).allowImportingTsExtensionssurprises. It requiresnoEmitoremitDeclarationOnly; enabling it to silence TS5097 in a project that emits JS produces a different error.- TS 5.x defaults moved.
ModuleResolutionKind.NodeJswas renamedNode10, and several templates still ship"node", which is treated as the legacy algorithm and ignoresexportsmaps entirely. skipLibCheckhides the symptom. It suppresses errors inside.d.tsfiles, so a brokentypescondition in a dependency can disappear in your build and reappear in a consumer's.
Related tools. Parse and normalise the import specifiers that keep failing with the URL encoder when paths contain spaces or query strings, diff two tsconfig files line by line with the text diff to see what an upgrade changed, and check the emitted .d.ts companion names by hashing built outputs with the hash generator across a rebuild.
Try matching browser tools
All toolsSmall utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related TypeScript guides
All TypeScript guidesTypeScript strict Mode: TS2531, TS7006, and TS18047 Migrations
strict is nine flags at once. Count errors per code, fix them in the order that keeps the build green, and narrow instead of asserting.
TypeScript Generic Parameter Defaults: Syntax, Precedence, and Inference
When a default applies and when inference wins, defaults that reference earlier parameters, and how a defaulted type parameter keeps a library change non-breaking.
TypeScript Branded Types: Nominal Typing, Type Tags, and Validation
How a phantom property makes two strings incompatible, unique symbol brands, unit-typed numbers, and the places where a brand quietly disappears.
TypeScript Ambient Declarations: .d.ts Files, declare, and declare global
How declare and .d.ts files describe runtime values, wildcard modules for assets, declare global with var, and module augmentation of third-party types.
More in TypeScript
All TypeScript guidesThe guides filed next to this one in TypeScript, in library order.