Module resolution strategy translates this sentence into English.

Module Resolution Strategies

TypeScript's module resolution strategy determines how the compiler locates imported modules. Understanding these strategies is crucial for resolving module reference issues and optimizing project structure. TypeScript supports two main strategies: Classic and Node, with the latter further divided into relative and non-relative path scenarios.

Classic Resolution Strategy

Classic is TypeScript's early module resolution strategy, now primarily used for backward compatibility. When using this strategy, TypeScript searches for modules in the following order:

1. Checks if the import path is relative (starting with ./ or ../)
2. If it's a relative path, directly looks for the file
3. If it's not a relative path, searches upward from the directory containing the importing file

// File structure:
// project/
//   src/
//     a.ts
//     lib/
//       b.ts

// In a.ts
import { foo } from 'lib/b' // Classic strategy will look for project/src/lib/b.ts

This strategy is simple but inflexible, especially when handling node_modules, so modern projects typically use the Node strategy.

Node Resolution Strategy

The Node strategy mimics Node.js's module resolution mechanism and is TypeScript's default strategy. It handles two scenarios based on the import method.

Relative Path Module Resolution

For imports starting with ./ or ../, the resolution process is as follows:

1. Directly looks for .ts/.tsx/.d.ts files at the specified path
2. If not found, attempts to find a directory with the same name (treated as a module) and its index file

// File structure:
// src/
//   components/
//     Button/
//       index.ts
//       styles.ts
//   utils.ts

// In Button/index.ts
import '../utils' // Directly looks for src/utils.ts
import './styles' // Looks for src/components/Button/styles.ts

Non-Relative Path Module Resolution

For non-relative path imports (e.g., using a module name directly), the resolution process is more complex:

1. Starts from the current file's directory and looks for the node_modules folder
2. Searches for matching modules in node_modules
3. If not found, recursively searches parent directories up to the project root
4. For each candidate location, checks the main/types fields in package.json

// File structure:
// project/
//   node_modules/
//     lodash/
//       package.json (main: "lodash.js")
//   src/
//     app/
//       deep/
//         module.ts

// In module.ts
import _ from 'lodash' // Resolved path: project/node_modules/lodash/lodash.js

Path Mapping and baseUrl

TypeScript allows customizing module resolution behavior through tsconfig.json.

baseUrl Configuration

baseUrl sets the base directory, and all non-relative path imports are resolved relative to this directory:

{
  "compilerOptions": {
    "baseUrl": "./src"
  }
}

// File structure:
// src/
//   components/
//     Button.tsx
//   pages/
//     Home.tsx

// In Home.tsx
import { Button } from 'components/Button' // Resolves to src/components/Button.tsx

paths Path Mapping

paths allows creating more complex module aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils": ["src/utils/index"]
    }
  }
}

// Using path mapping
import { Button } from '@components/Button'
import { format } from '@utils'

Practical Applications of Module Resolution

Understanding module resolution strategies helps resolve common issues:

1. Handling Circular Dependencies: By refactoring modules or using lazy imports

// a.ts
import { b } from './b'

// b.ts
// Error: Circular dependency
import { a } from './a'

// Solution: Lazy import
export function b() {
  import('./a').then(({ a }) => a())
}

2. Type Declaration File Resolution: When importing third-party libraries, TypeScript prioritizes .d.ts files

// node_modules/foo/
//   package.json
//   index.js
//   index.d.ts

import { bar } from 'foo' // Uses type declarations from index.d.ts

3. Multi-Environment Configuration: Adapting to different environments with separate tsconfig.json files

// tsconfig.web.json
{
  "compilerOptions": {
    "paths": {
      "env/*": ["./src/env/web/*"]
    }
  }
}

// tsconfig.node.json
{
  "compilerOptions": {
    "paths": {
      "env/*": ["./src/env/node/*"]
    }
  }
}

Advanced Module Resolution Techniques

1. Using Symbolic Links: Creating local module links via npm link or yarn link

# In the module directory
npm link

# In the project directory
npm link my-module

2. Project References: Splitting large projects into multiple subprojects

// tsconfig.json
{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

3. Custom Module Resolution: Implementing custom resolution logic via the ModuleResolutionHost interface

import * as ts from 'typescript'

class CustomResolver implements ts.ModuleResolutionHost {
  // Implement required methods
}

const resolver = ts.createModuleResolver(
  new CustomResolver(),
  compilerOptions,
  moduleResolutionCache
)

Performance Optimization Considerations

Module resolution strategies impact compilation performance:

1. Reduce Deeply Nested node_modules Lookups: Flatten dependency trees
2. Use Path Mapping Judiciously: Avoid overly complex path patterns
3. Leverage Resolution Caching: TypeScript caches resolved module paths
4. Avoid Excessive Relative Path Jumps: E.g., "../../../../utils"

// Not recommended
import { util } from '../../../../utils'

// Recommended
import { util } from '@project/utils'

Common Issue Troubleshooting

When encountering module resolution issues, you can:

1. Use the --traceResolution flag to view detailed resolution process

tsc --traceResolution

2. Check typescript/lib/tsserver.log for resolution logs
3. Verify if tsconfig.json is loaded correctly

// Print the configuration used by the compiler
console.log(require('typescript').sys.readFile('tsconfig.json'))

4. Ensure file extensions are correct, especially across different operating systems

// Windows may be case-insensitive, but Linux/Mac are case-sensitive
import { Button } from './button' // Actual file is Button.tsx