Module resolution configuration

Module Resolution Configuration

TypeScript's module resolution mechanism determines how the compiler locates imported modules. Understanding and correctly configuring the module resolution strategy is crucial for project structure organization and module referencing. TypeScript supports various module resolution strategies, including Node.js's resolution algorithm and relative path resolution.

Module Resolution Strategies

TypeScript provides two main module resolution strategies:

1. Classic: TypeScript's early default strategy, now mainly used for backward compatibility
2. Node: Simulates Node.js's module resolution mechanism, the recommended choice for modern TypeScript projects

You can configure this via the moduleResolution option in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

Node Module Resolution Algorithm

When using the Node resolution strategy, TypeScript searches for modules in the following order:

1. Checks if it is a core Node.js module (e.g., fs, path, etc.)
2. Checks the node_modules folder in the current directory
3. Looks for node_modules in parent directories until reaching the filesystem root
4. Searches directories specified by the NODE_PATH environment variable

For file path resolution, TypeScript attempts the following extensions:

• .ts
• .tsx
• .d.ts
• .js
• .jsx (when allowJs is true)

Path Mapping Configuration

The paths configuration allows creating module aliases or custom import paths, which is particularly useful in large projects:

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

This enables imports like the following in code:

import { Button } from '@components/Button';
import { formatDate } from '@utils/date';

baseUrl Configuration

baseUrl allows setting the base directory for module resolution. All non-relative imports are resolved relative to this directory:

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

After setting this, you can import directly from the src directory:

import { api } from 'services/api';  // Actually resolves to ./src/services/api

Type Resolution and Type Roots

TypeScript searches for type definition files for modules. The typeRoots option specifies where to look for type definition files:

{
  "compilerOptions": {
    "typeRoots": [
      "./typings",
      "./node_modules/@types"
    ]
  }
}

Practical Example of Module Resolution

Assume the following project structure:

project/
├── src/
│   ├── components/
│   │   └── Button.tsx
│   ├── utils/
│   │   └── date.ts
│   └── index.ts
├── typings/
│   └── custom.d.ts
└── tsconfig.json

The corresponding tsconfig.json configuration:

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@components/*": ["components/*"],
      "@utils/*": ["utils/*"]
    },
    "typeRoots": [
      "../typings",
      "./node_modules/@types"
    ],
    "moduleResolution": "node"
  }
}

In index.ts, you can import like this:

import { Button } from '@components/Button';
import { formatDate } from '@utils/date';
import { SomeType } from 'custom';  // Imported from typings/custom.d.ts

Common Issues and Solutions

1. Cannot Find Module Declaration File

   When importing a third-party library that lacks type definitions, you can:

   • Install the corresponding @types/ package
   • Declare the module type in the project
   • Add "skipLibCheck": true to tsconfig.json

2. Path Mapping Doesn't Work at Runtime

   Path mapping only affects TypeScript compilation. For runtime, additional configuration is needed:

   • Use the tsconfig-paths package
   • Or configure the module loader (e.g., Webpack's resolve.alias)

3. Circular Dependency Issues

   When module A imports module B, and module B also imports module A, resolution issues may arise. Solutions:

   • Refactor code to eliminate circular dependencies
   • Use lazy imports (dynamic import)

Advanced Configuration Techniques

1. Multi-Project Workspace Configuration

   In monorepo projects, you can configure composite projects:

   {
     "compilerOptions": {
       "composite": true,
       "baseUrl": ".",
       "paths": {
         "@shared/*": ["shared/src/*"]
       }
     },
     "references": [
       { "path": "../shared" }
     ]
   }
   

2. Custom Module Suffix Resolution

   Although not directly configurable, you can simulate it with multiple paths entries:

   {
     "paths": {
       "*": [
         "*",
         "*.ts",
         "*.tsx",
         "*.d.ts",
         "*.js"
       ]
     }
   }
   

3. Environment-Specific Configuration

   Use extends to inherit a base configuration and override specific settings:

   // tsconfig.base.json
   {
     "compilerOptions": {
       "moduleResolution": "node",
       "baseUrl": "./src"
     }
   }
   
   // tsconfig.prod.json
   {
     "extends": "./tsconfig.base",
     "compilerOptions": {
       "paths": {
         "@config": ["config/prod"]
       }
     }
   }
   

Performance Optimization Considerations

1. Avoid Excessive Path Mappings

   Each path mapping increases module resolution time, so keep path mappings concise.

2. Set typeRoots Appropriately

   Only include directories that actually contain type definitions to reduce unnecessary type lookups.

3. Use Project References

   For large projects, use references to split the codebase and improve incremental build speed.

4. Enable resolveJsonModule

   If you need to import JSON files, explicitly enable it:

   {
     "compilerOptions": {
       "resolveJsonModule": true
     }
   }
   

Integration with Other Tools

1. Webpack Integration

   Ensure Webpack's resolve configuration aligns with TypeScript:

   const path = require('path');
   
   module.exports = {
     resolve: {
       alias: {
         '@components': path.resolve(__dirname, 'src/components'),
       },
       extensions: ['.ts', '.tsx', '.js', '.json']
     }
   };
   

2. Jest Test Configuration

   Match TypeScript's path mappings in Jest:

   module.exports = {
     moduleNameMapper: {
       '^@components/(.*)$': '<rootDir>/src/components/$1',
     }
   };
   

3. ESLint Import Resolution

   Configure eslint-import-resolver-typescript to correctly resolve path mappings:

   settings: {
     'import/resolver': {
       typescript: {
         alwaysTryTypes: true,
       },
     },
   }