ProgramGuru

Module Resolution

Module Resolution — the core idea

Module resolution finds the file or package an import refers to. Resolution may consult relative paths, package.json exports, and installed type declarations. The TypeScript resolver should model the runtime or bundler that will actually load emitted code.

What you’ll learn

  • Explain module resolution with a concrete use case.
  • Run the example and account for every line of its output.
  • Recognize the difference between compile-time checking and runtime behavior.

Understand the rules and when to use them

Reading the code: The program exports answer and readable locally. A consumer's `./config.js` specifier is resolved relative to its own location. Resolving a type declaration alone does not guarantee a matching implementation exists.

Keep the boundary clear: Do not use compiler paths aliases as if Node automatically understands them in emitted imports; a runtime resolver or build rewrite may be needed.

See the idea as a flow

Module Resolution — conceptual flowimport specifier then resolve file/package then load emitted moduleModule Resolution1import specifier2resolve file/package3load emitted moduleMatch the compiler configuration to the JavaScript environment.
Follow the three stages and identify what happens in TypeScript versus JavaScript.

Run the complete TypeScript example

Save the code as module-resolution.ts. The result below was captured after compiling this exact example with strict TypeScript checking and executing the emitted JavaScript in Node.js.

TypeScript code

export const answer = 42;
export function readable(value: number): string { return `answer=${value}`; }
console.log(readable(answer));

Verified output

answer=42

Build: npx tsc --strict --target es2022 --module commonjs --lib es2022,dom,esnext.disposable module-resolution.ts; run: node module-resolution.js. The exact filename may be changed freely. When a multi-file project exists, prefer its tsconfig.json and build scripts.

Trace the example line by line

The program exports answer and readable locally. A consumer's ./config.js specifier is resolved relative to its own location. Resolving a type declaration alone does not guarantee a matching implementation exists.

The output shown above comes from the initialized values in this program. Replacing a type annotation alone does not transform a JavaScript value.

Build the real multi-file example

This separate mini-project demonstrates real imports, exports, or declarations across files. Create each file in one folder, then compile and run main.js. The example was checked separately from the single-file program.

config.ts

export const retries=3;

main.ts

import {retries} from "./config";console.log(retries);

CommonJS setup: compile with npx tsc --strict --target es2022 --module commonjs main.ts and run node main.js. Compile from the same directory so relative modules are discovered. If this example contains helpers.js, keep that runtime file alongside the emitted main.js.

Verified output from the mini-project

3

Avoid this common mistake

Do not use compiler paths aliases as if Node automatically understands them in emitted imports; a runtime resolver or build rewrite may be needed.

Check both the TypeScript diagnostic and the emitted JavaScript behavior. A program can compile correctly and still need runtime validation or error handling.

Practice independently

Create src/config.ts and src/main.ts with a relative import; compare a working relative specifier with a misspelled one.

Before running your change, write down the type you expect TypeScript to infer and the output you expect JavaScript to print. Then check both predictions.

Check your understanding

What is module resolution responsible for?
Choose one answer. You can try again.

Answer and explanation

Finding the module or declaration a specifier refers to.

The program exports answer and readable locally. A consumer's `./config.js` specifier is resolved relative to its own location. Resolving a type declaration alone does not guarantee a matching implementation exists.

What to remember

Module resolution finds the file or package an import refers to.

Try the practice change and re-run the exact program to test your understanding.

Reaching the recap and completing the quizzes are separate milestones.

    Next lesson: NodeNext and Bundler Resolution →