Module resolution

Intermediate · 8 min

How TypeScript finds the file behind an import under nodenext and bundler, why extensions and exports matter, and what paths does and doesn't do.

Before thistsconfig explainedModules and type-only imports

Michigan TypeScript · 8 min

Module resolution

The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.

Taught by Michigan TypeScriptReport a problem with this video
Not started
Set this lesson's status

What you'll learn

  • Module resolution is how the compiler turns an import string like `"./db.js"` or `"zod"` into a file it can read types from. It must copy the rules of whatever will load the code at runtime, or checks pass on imports that fail.
  • `node16` and `nodenext` copy Node: relative ESM imports need a file extension, `package.json` `"type"` decides whether a `.ts` file is ESM or CommonJS, and a package's `exports` map limits what you can import.
  • In `nodenext`, you write the extension of the output file, so `./db.ts` is imported as `./db.js`.
  • `bundler` copies what Vite, esbuild, and webpack do: extensionless relative imports work, and `exports` maps are still respected. Pair it with `module: "preserve"` or `esnext`.
  • `paths` changes only where the compiler looks. It never rewrites the import in the output, so the bundler or runtime needs a matching alias of its own.

The compiler has to find the same file the runtime will

Every import has a string in it: "./db.js", "zod", "@/lib/math". To check the code, TypeScript has to turn that string into a file and read its types. That lookup is module resolution.

TypeScript doesn’t load anything at runtime. Node or a bundler does that later, each with its own rules. So the compiler’s job is to copy the rules of the real loader. If it’s more lenient, you get imports that type-check and then crash. If it’s stricter, you get errors on code that would work.

Think of it as a mail sorter learning the postal rules of the country the letter is going to. The moduleResolution option tells it which country. Modern projects pick one of two.

nodenext: code that Node runs

Choose module: "nodenext" (it sets moduleResolution to match) when Node loads your compiled output. node16 is the same idea frozen at Node 16’s behavior, so nodenext is the usual choice. Three Node rules come with it.

ESM or CommonJS depends on the nearest package.json. With "type": "module", .ts files are treated as ES modules. Without it, they’re CommonJS. .mts and .cts force one or the other regardless.

Relative ESM imports need an extension. Node’s ESM loader doesn’t guess, so neither does the compiler:

import { add } from "./lib/math";     // error TS2835: Relative import paths need
                                      // explicit file extensions ... Did you mean './lib/math.js'?
import { add } from "./lib/math.js";  // ok

Note it’s .js, not .ts. You write the name of the file that will exist after compiling, and the compiler maps it back to math.ts for the types. If you run .ts files directly with Node’s type stripping, you write .ts instead and turn on rewriteRelativeImportExtensions so a later tsc build fixes the extension.

A package’s exports map controls what you can import. Given this in a dependency:

{
  "name": "pkg",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./utils": "./dist/utils.js"
  }
}

import "pkg" and import "pkg/utils" work. import "pkg/dist/internal.js" fails with “Cannot find module”, even though the file is right there, because the map doesn’t list it. The keys inside "." are conditions. The compiler picks the branch that matches how the import is made, import from ESM files and require from CommonJS, and prefers a types entry when one exists.

bundler: code a bundler reads

Most frontend code is never loaded by Node. Vite, esbuild, or webpack read the imports and are far more forgiving. moduleResolution: "bundler" copies that:

{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
    "noEmit": true
  }
}

Extensionless relative imports like "./lib/math" are fine, and so are directory imports that resolve to an index file. exports maps still apply. Bundlers respect them, so the compiler does too. Pair bundler with module: "preserve" (or esnext). preserve leaves your imports as written, which is what you want when the bundler handles the rest.

The rule of thumb from the tsconfig lesson still holds: if Node runs it, nodenext; if a bundler builds it, bundler. Using bundler for a Node server will let through imports that Node rejects at startup.

paths: aliases for the compiler only

Deep relative imports like ../../../lib/math.js get tiresome, so many projects define an alias:

{
  "compilerOptions": {
    "module": "nodenext",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
import { add } from "@/lib/math.js";

The editor and tsc are now happy. Compile it, though, and the output still reads:

import { add } from "@/lib/math.js";

paths changes where the compiler looks, not what it writes. Node will crash on that line, because @/ means nothing to it. The alias has to exist in the runtime as well: Vite’s resolve.alias, a matching bundler plugin, or tsx, which reads paths itself. For code that Node runs, the better tool is Node’s own imports field in package.json (aliases starting with #), which both Node and nodenext resolution understand.

Older configs pair paths with baseUrl. That’s no longer needed. paths entries resolve relative to the tsconfig, and TypeScript 6.0 deprecates baseUrl.

What the video covers

Ian VanSchooten’s lightning talk is focused on moduleResolution: "bundler", the mode added in TypeScript 5.0: why it was needed and how it differs from node16 and nodenext. It doesn’t touch paths, which is why that section above is longer. For the Node side, his follow-up on TypeScript 5.2, linked below, explains why module and moduleResolution have to match under Node settings. The hour-long deep dive is there for when you’re debugging a resolution failure and want to see the whole algorithm. It predates bundler mode.

Check yourself

  1. 01Under `module: "nodenext"` in a package with `"type": "module"`, why does `import { db } from "./db"` fail even though `db.ts` exists?

    Node's ESM loader doesn't add file extensions, so at runtime it would look for a file literally named `db` and fail. `nodenext` copies that rule and asks for an explicit extension, written as `./db.js` because that is the file that will exist after compiling.

  2. 02A package's `package.json` has an `exports` map listing only `"."` and `"./utils"`. Why can't you import `pkg/dist/internal.js`, even though the file is on disk?

    When a package has an `exports` map, Node only lets consumers reach the paths that map lists. Both `nodenext` and `bundler` resolution follow the same rule, so anything outside the map is reported as not found.

  3. 03You add `"paths": { "@/*": ["./src/*"] }` and the editor is happy, but `node dist/main.js` crashes on `@/lib/math.js`. Why?

    `paths` only tells the compiler where to find types. The emitted JavaScript still says `@/lib/math.js`, and Node has no idea what `@/` means. The alias also needs to be configured in whatever runs the code, or replaced with Node's own `imports` field in `package.json`.

  4. 04When should a project use `moduleResolution: "bundler"` instead of `nodenext`?

    When a bundler, not Node, reads your imports, as in most frontend apps. If Node runs the compiled output directly, `bundler` would allow imports Node rejects, so `nodenext` is the safe choice there.

Go deeper

Notes

Private to you

Esc
↑↓ navigate↵ open? shortcuts

Keyboard shortcuts

Press Esc to close

Anywhere

⌘K
Search and commands
/
Search
?
This sheet
Esc
Close

Reading a lesson

J
Next lesson
K
Previous lesson
B
Bookmark