Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readTypeScript
#TypeScript#ESM#Node.js#tsconfig
3D illustration of a file cube with a missing puzzle piece and a dotted broken link to a package cube

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:

jsonc
// 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"] }
ts
// 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.ts

With "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:

jsonc
{ "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

moduleResolutionExtension requiredDirectory indexexports mapUse when
node10 (legacy node)NoYesIgnoredOld CJS projects only
node16 / nodenextYes, in ESM filesNoEnforcedNode apps, libraries, CLIs
bundlerNoYesEnforcedNext.js, Vite, webpack
classicNoNoIgnoredDo not use
ErrorReal causeFix
TS2835Extensionless relative import in ESMAdd .js
TS2307 on a relative pathFile missing, or .jsx/.mts mismatchFix the path or the extension
TS2307 on a packageMissing exports subpath or typesAdd both to the package
TS7016Package has no bundled typesnpm i -D @types/… or a local declaration
TS1479Importing ESM from CJS outputUse await import() or dual publish
TS5097.ts extension in importEnable 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.

ts
// src/db/client.ts import { pool } from '../lib/pool.js'; // resolves src/lib/pool.ts, emits dist/lib/pool.js

Do 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.

ts
import { x } from './lib/index.js'; // explicit file, no directory fallback

3. 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.

jsonc
{ "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:

ts
// 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.

ts
import type { Config } from './config.js'; // erased import { createServer } from './server.js'; // kept

6. 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:

bash
node --loader ts-node/esm src/index.ts # or, simpler and faster npx tsx src/index.ts

tsx 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" with module: "commonjs". Invalid combination; TypeScript requires module to be esnext, preserve or similar. The error message names the pair, not the app's real problem.
  • "type": "module" plus .js files that are CJS. Every .js becomes ESM and require() inside them fails. Rename to .cjs or convert.
  • exports breaking deep imports. Adding exports hides acme-utils/dist/internal.js that consumers imported directly. Add explicit subpaths before publishing a minor release.
  • types after import in exports. Condition order is significant: with import first, TypeScript may resolve the JavaScript file and then fail to find types for it (TS7016 in the consumer).
  • allowImportingTsExtensions surprises. It requires noEmit or emitDeclarationOnly; enabling it to silence TS5097 in a project that emits JS produces a different error.
  • TS 5.x defaults moved. ModuleResolutionKind.NodeJs was renamed Node10, and several templates still ship "node", which is treated as the legacy algorithm and ignores exports maps entirely.
  • skipLibCheck hides the symptom. It suppresses errors inside .d.ts files, so a broken types condition 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 tools

Small utilities that fit TypeScript work — they run entirely in this browser tab, so nothing you paste leaves your device.

All TypeScript guides

More in TypeScript

All TypeScript guides

The guides filed next to this one in TypeScript, in library order.