Module Resolution

Module resolution decides how TypeScript turns an import path like 'lodash' or './util.js' into an actual file on disk. Picking the wrong strategy is a top source of "works in editor, breaks in CI" pain.

The choices

NodeNext rules of the road

• Imports must include the file extension — but it's the output extension (.js) even though source is .ts:

import { foo } from './bar.js';     // source is bar.ts
import { x }   from './sub/index.js';

• Honours "exports" in package.json — same as Node itself.
• Different CJS / ESM resolution depending on the package's own type.

Bundler rules

• You can omit extensions; the bundler fills them in.
• Honours "imports", "exports", plus aliasing.
• Simpler in source — but only safe if you really use a bundler at build time.

resolveJsonModule

// tsconfig: "resolveJsonModule": true
import data from './fixtures/users.json';

const first = data[0].name;     // typed as the literal shape of users.json

moduleSuffixes

For per-platform variants (.ios.ts, .web.ts):

{
    "compilerOptions": {
        "moduleSuffixes": [".web", ""]
    }
}

baseUrl + paths — alias resolution

Pairs with paths from the previous lesson. Aliases resolve before module resolution does its normal lookup.

Example

// 'NodeNext' (modern) — uses package.json exports
// 'Bundler' (Vite, esbuild) — relaxed, follows the bundler
// 'Node10' (legacy)
//
// resolveJsonModule — import data.json as a typed object
console.log('Pick NodeNext or Bundler for new projects');

Exercise

Test yourself