🔍 Module Resolution: How TypeScript Finds Modules

🎯 Introduction

Welcome to the detective world of module resolution! 🔍 If TypeScript were Sherlock Holmes, then module resolution would be its greatest mystery-solving skill - it can track down any module from the smallest clue, following intricate paths through your filesystem until it finds exactly what you’re looking for!

Module resolution is the process by which TypeScript determines what file an import statement refers to. Understanding this process is crucial for organizing large codebases, optimizing build times, and avoiding frustrating “cannot find module” errors. Whether you’re working with relative imports, npm packages, or custom path mappings, mastering module resolution will make you a more effective TypeScript developer.

By the end of this tutorial, you’ll be a module resolution expert, capable of understanding exactly how TypeScript finds your modules and how to structure your projects for optimal development experience. Let’s dive into the fascinating world of module discovery! 🌟

📚 Understanding Module Resolution

🤔 What Is Module Resolution?

Module resolution is the process TypeScript uses to figure out what the import in an import statement refers to. When you write import { someFunction } from './utils', TypeScript needs to determine exactly which file to load based on that import specifier.

// 🌟 Different types of module imports that need resolution
// Each of these requires TypeScript to follow different resolution strategies

// 📁 Relative imports - resolved relative to the importing file
import { UserService } from './services/UserService';
import { ApiClient } from '../api/ApiClient';
import { Constants } from '../../config/constants';

// 📦 Node modules - resolved from node_modules
import express from 'express';
import { Observable } from 'rxjs';
import lodash from 'lodash';

// 🎯 Path-mapped imports - resolved using baseUrl and paths
import { Button } from '@/components/Button';
import { ApiService } from '@services/ApiService';
import { UserType } from '@types/User';

// 🔧 Ambient modules - declared but not necessarily files
import 'reflect-metadata';
import '@/styles/global.css';

// 🌍 External modules with specific extensions
import data from './data.json';
import styles from './Component.module.css';
import worker from './worker?worker';

// 🎮 Let's create a comprehensive example that demonstrates resolution
console.log('🔍 Module Resolution Examples');

// 📦 Example: TypeScript resolving a complex import hierarchy
// src/
//   components/
//     ui/
//       Button/
//         index.ts
//         Button.tsx
//         Button.module.css
//         Button.test.ts
//   services/
//     api/
//       UserService.ts
//       ApiClient.ts
//   utils/
//     validation/
//       userValidation.ts
//   types/
//     User.ts
//     Api.ts

// 🎯 From src/components/ui/Button/Button.tsx
// These imports will be resolved using different strategies:

// ✅ Relative import - looks for ../../../services/api/UserService.ts
// import { UserService } from '../../../services/api/UserService';

// ✅ Path-mapped import (if configured) - looks using baseUrl + paths
// import { UserService } from '@services/api/UserService';

// ✅ Node module import - looks in node_modules/react/
// import React from 'react';

// ✅ Type-only import - doesn't affect runtime, only compilation
// import type { User } from '@types/User';

// 🔧 Module resolution demonstration class
class ModuleResolutionDemo {
  // 📊 Track resolution statistics
  private resolutionStats = {
    successful: 0,
    failed: 0,
    cached: 0,
    totalTime: 0
  };

  // 🔍 Simulate TypeScript's module resolution process
  async resolveModule(
    importSpecifier: string,
    containingFile: string,
    compilerOptions: any
  ): Promise<{
    resolvedFileName?: string;
    isExternalLibraryImport?: boolean;
    resolvedModule?: any;
    failedLookupLocations?: string[];
  }> {
    const startTime = performance.now();
    
    console.log(`🔍 Resolving module: "${importSpecifier}" from "${containingFile}"`);
    
    try {
      // 🎯 Determine resolution strategy based on import type
      if (this.isRelativeImport(importSpecifier)) {
        console.log('📁 Using relative resolution strategy');
        return await this.resolveRelativeImport(importSpecifier, containingFile, compilerOptions);
      } else {
        console.log('📦 Using node resolution strategy');
        return await this.resolveNodeImport(importSpecifier, containingFile, compilerOptions);
      }
    } catch (error) {
      this.resolutionStats.failed++;
      console.error(`❌ Failed to resolve "${importSpecifier}":`, error);
      throw error;
    } finally {
      const endTime = performance.now();
      this.resolutionStats.totalTime += endTime - startTime;
      console.log(`⏱️ Resolution took ${(endTime - startTime).toFixed(2)}ms`);
    }
  }

  // 📁 Check if import is relative
  private isRelativeImport(importSpecifier: string): boolean {
    return importSpecifier.startsWith('./') || 
           importSpecifier.startsWith('../') || 
           importSpecifier.startsWith('/');
  }

  // 📁 Resolve relative imports
  private async resolveRelativeImport(
    importSpecifier: string,
    containingFile: string,
    compilerOptions: any
  ): Promise<any> {
    console.log(`📁 Resolving relative import: ${importSpecifier}`);
    
    // 🗂️ Calculate base directory
    const containingDir = this.getDirectoryPath(containingFile);
    const resolvedPath = this.resolvePath(containingDir, importSpecifier);
    
    console.log(`📍 Base directory: ${containingDir}`);
    console.log(`🎯 Resolved path: ${resolvedPath}`);
    
    // 🔍 Try different file extensions
    const extensions = ['.ts', '.tsx', '.js', '.jsx', '.d.ts'];
    const failedLookupLocations: string[] = [];
    
    for (const ext of extensions) {
      const candidate = `${resolvedPath}${ext}`;
      console.log(`🔍 Trying: ${candidate}`);
      
      if (await this.fileExists(candidate)) {
        console.log(`✅ Found file: ${candidate}`);
        this.resolutionStats.successful++;
        
        return {
          resolvedFileName: candidate,
          isExternalLibraryImport: false,
          resolvedModule: { resolvedFileName: candidate }
        };
      }
      
      failedLookupLocations.push(candidate);
    }
    
    // 🗂️ Try index files
    const indexCandidates = extensions.map(ext => `${resolvedPath}/index${ext}`);
    
    for (const candidate of indexCandidates) {
      console.log(`🔍 Trying index file: ${candidate}`);
      
      if (await this.fileExists(candidate)) {
        console.log(`✅ Found index file: ${candidate}`);
        this.resolutionStats.successful++;
        
        return {
          resolvedFileName: candidate,
          isExternalLibraryImport: false,
          resolvedModule: { resolvedFileName: candidate }
        };
      }
      
      failedLookupLocations.push(candidate);
    }
    
    // ❌ No file found
    this.resolutionStats.failed++;
    return {
      failedLookupLocations
    };
  }

  // 📦 Resolve node modules
  private async resolveNodeImport(
    importSpecifier: string,
    containingFile: string,
    compilerOptions: any
  ): Promise<any> {
    console.log(`📦 Resolving node import: ${importSpecifier}`);
    
    // 🎯 Check if it's a path-mapped import
    if (compilerOptions.baseUrl && compilerOptions.paths) {
      const pathMappedResult = await this.tryPathMapping(
        importSpecifier,
        compilerOptions.baseUrl,
        compilerOptions.paths
      );
      
      if (pathMappedResult.resolvedFileName) {
        console.log(`🗺️ Resolved via path mapping: ${pathMappedResult.resolvedFileName}`);
        return pathMappedResult;
      }
    }
    
    // 📦 Try node_modules resolution
    return await this.resolveFromNodeModules(importSpecifier, containingFile);
  }

  // 🗺️ Try path mapping resolution
  private async tryPathMapping(
    importSpecifier: string,
    baseUrl: string,
    paths: Record<string, string[]>
  ): Promise<any> {
    console.log(`🗺️ Trying path mapping for: ${importSpecifier}`);
    console.log(`📍 Base URL: ${baseUrl}`);
    console.log(`🗺️ Paths:`, paths);
    
    // 🔍 Find matching path pattern
    for (const [pattern, substitutions] of Object.entries(paths)) {
      console.log(`🔍 Checking pattern: ${pattern}`);
      
      const match = this.matchPattern(pattern, importSpecifier);
      if (match) {
        console.log(`✅ Pattern matched: ${pattern}`);
        console.log(`🎯 Captured groups:`, match.groups);
        
        // 🔄 Try each substitution
        for (const substitution of substitutions) {
          const resolvedPath = this.substitutePattern(substitution, match.groups, baseUrl);
          console.log(`🔄 Trying substitution: ${resolvedPath}`);
          
          // 🔍 Check if resolved file exists
          const extensions = ['.ts', '.tsx', '.js', '.jsx', '.d.ts'];
          
          for (const ext of extensions) {
            const candidate = `${resolvedPath}${ext}`;
            
            if (await this.fileExists(candidate)) {
              console.log(`✅ Found via path mapping: ${candidate}`);
              this.resolutionStats.successful++;
              
              return {
                resolvedFileName: candidate,
                isExternalLibraryImport: false,
                resolvedModule: { resolvedFileName: candidate }
              };
            }
          }
          
          // 🗂️ Try index files
          for (const ext of extensions) {
            const candidate = `${resolvedPath}/index${ext}`;
            
            if (await this.fileExists(candidate)) {
              console.log(`✅ Found index via path mapping: ${candidate}`);
              this.resolutionStats.successful++;
              
              return {
                resolvedFileName: candidate,
                isExternalLibraryImport: false,
                resolvedModule: { resolvedFileName: candidate }
              };
            }
          }
        }
      }
    }
    
    console.log(`❌ No path mapping match found for: ${importSpecifier}`);
    return {};
  }

  // 📦 Resolve from node_modules
  private async resolveFromNodeModules(
    importSpecifier: string,
    containingFile: string
  ): Promise<any> {
    console.log(`📦 Resolving from node_modules: ${importSpecifier}`);
    
    // 🔍 Walk up directory tree looking for node_modules
    let currentDir = this.getDirectoryPath(containingFile);
    const failedLookupLocations: string[] = [];
    
    while (currentDir !== '/') {
      const nodeModulesPath = `${currentDir}/node_modules`;
      console.log(`🔍 Checking: ${nodeModulesPath}`);
      
      if (await this.directoryExists(nodeModulesPath)) {
        // 📦 Try to resolve the package
        const packageResult = await this.resolvePackage(
          nodeModulesPath,
          importSpecifier
        );
        
        if (packageResult.resolvedFileName) {
          console.log(`✅ Resolved from node_modules: ${packageResult.resolvedFileName}`);
          this.resolutionStats.successful++;
          
          return {
            ...packageResult,
            isExternalLibraryImport: true
          };
        }
        
        failedLookupLocations.push(...(packageResult.failedLookupLocations || []));
      }
      
      // 📁 Move up one directory
      currentDir = this.getParentDirectory(currentDir);
    }
    
    console.log(`❌ Could not resolve from node_modules: ${importSpecifier}`);
    this.resolutionStats.failed++;
    
    return {
      failedLookupLocations
    };
  }

  // 📦 Resolve package from node_modules
  private async resolvePackage(
    nodeModulesPath: string,
    packageName: string
  ): Promise<any> {
    console.log(`📦 Resolving package: ${packageName} in ${nodeModulesPath}`);
    
    const [scopeOrName, ...rest] = packageName.split('/');
    let actualPackageName: string;
    let subPath: string;
    
    // 🔍 Handle scoped packages (@scope/package)
    if (scopeOrName.startsWith('@')) {
      actualPackageName = `${scopeOrName}/${rest[0]}`;
      subPath = rest.slice(1).join('/');
    } else {
      actualPackageName = scopeOrName;
      subPath = rest.join('/');
    }
    
    const packageDir = `${nodeModulesPath}/${actualPackageName}`;
    console.log(`📁 Package directory: ${packageDir}`);
    console.log(`🗂️ Sub-path: ${subPath || '(none)'}`);
    
    if (!(await this.directoryExists(packageDir))) {
      console.log(`❌ Package directory not found: ${packageDir}`);
      return {
        failedLookupLocations: [packageDir]
      };
    }
    
    // 📄 Read package.json
    const packageJsonPath = `${packageDir}/package.json`;
    let packageJson: any = {};
    
    if (await this.fileExists(packageJsonPath)) {
      try {
        packageJson = await this.readJsonFile(packageJsonPath);
        console.log(`📄 Read package.json:`, packageJson.name, packageJson.version);
      } catch (error) {
        console.warn(`⚠️ Failed to read package.json: ${packageJsonPath}`);
      }
    }
    
    // 🎯 Resolve entry point
    if (subPath) {
      // 📁 Resolving sub-path
      const subPathResolved = `${packageDir}/${subPath}`;
      return await this.resolveFile(subPathResolved);
    } else {
      // 📦 Resolving main entry point
      return await this.resolveMainEntry(packageDir, packageJson);
    }
  }

  // 📄 Resolve main entry point
  private async resolveMainEntry(packageDir: string, packageJson: any): Promise<any> {
    console.log(`📄 Resolving main entry for package in: ${packageDir}`);
    
    // 🎯 Try different entry point fields in order
    const entryFields = ['types', 'typings', 'main', 'module', 'index'];
    const failedLookupLocations: string[] = [];
    
    for (const field of entryFields) {
      if (packageJson[field]) {
        const entryPath = `${packageDir}/${packageJson[field]}`;
        console.log(`🔍 Trying ${field} field: ${entryPath}`);
        
        const result = await this.resolveFile(entryPath);
        if (result.resolvedFileName) {
          console.log(`✅ Resolved via ${field}: ${result.resolvedFileName}`);
          return result;
        }
        
        failedLookupLocations.push(...(result.failedLookupLocations || []));
      }
    }
    
    // 🗂️ Try default index files
    const indexFiles = ['index.ts', 'index.tsx', 'index.js', 'index.jsx', 'index.d.ts'];
    
    for (const indexFile of indexFiles) {
      const indexPath = `${packageDir}/${indexFile}`;
      console.log(`🔍 Trying default index: ${indexPath}`);
      
      if (await this.fileExists(indexPath)) {
        console.log(`✅ Found default index: ${indexPath}`);
        return {
          resolvedFileName: indexPath,
          resolvedModule: { resolvedFileName: indexPath }
        };
      }
      
      failedLookupLocations.push(indexPath);
    }
    
    console.log(`❌ Could not resolve main entry for package in: ${packageDir}`);
    return {
      failedLookupLocations
    };
  }

  // 📄 Resolve file with extensions
  private async resolveFile(filePath: string): Promise<any> {
    const extensions = ['.ts', '.tsx', '.js', '.jsx', '.d.ts', ''];
    const failedLookupLocations: string[] = [];
    
    for (const ext of extensions) {
      const candidate = filePath + ext;
      
      if (await this.fileExists(candidate)) {
        return {
          resolvedFileName: candidate,
          resolvedModule: { resolvedFileName: candidate }
        };
      }
      
      failedLookupLocations.push(candidate);
    }
    
    return {
      failedLookupLocations
    };
  }

  // 🔧 Utility methods (simulated for demonstration)
  private getDirectoryPath(filePath: string): string {
    return filePath.substring(0, filePath.lastIndexOf('/')) || '/';
  }

  private getParentDirectory(dirPath: string): string {
    const parent = dirPath.substring(0, dirPath.lastIndexOf('/')) || '/';
    return parent === dirPath ? '/' : parent;
  }

  private resolvePath(basePath: string, relativePath: string): string {
    // Simplified path resolution
    if (relativePath.startsWith('./')) {
      return `${basePath}/${relativePath.substring(2)}`;
    } else if (relativePath.startsWith('../')) {
      const parentDir = this.getParentDirectory(basePath);
      return this.resolvePath(parentDir, relativePath.substring(3));
    } else {
      return `${basePath}/${relativePath}`;
    }
  }

  private matchPattern(pattern: string, input: string): { groups: string[] } | null {
    // Simple pattern matching for path mapping
    const regexPattern = pattern.replace(/\*/g, '(.*)');
    const regex = new RegExp(`^${regexPattern}$`);
    const match = input.match(regex);
    
    return match ? { groups: match.slice(1) } : null;
  }

  private substitutePattern(substitution: string, groups: string[], baseUrl: string): string {
    let result = substitution;
    groups.forEach((group, index) => {
      result = result.replace(/\*/g, group);
    });
    return `${baseUrl}/${result}`;
  }

  // 🔧 File system simulation methods
  private async fileExists(path: string): Promise<boolean> {
    // In real implementation, this would check the actual file system
    // For demo purposes, we'll simulate some existing files
    const simulatedFiles = [
      '/project/src/components/Button.ts',
      '/project/src/services/UserService.ts',
      '/project/src/utils/validation.ts',
      '/project/node_modules/react/index.js',
      '/project/node_modules/lodash/index.js',
    ];
    
    return simulatedFiles.includes(path);
  }

  private async directoryExists(path: string): Promise<boolean> {
    // Simulate directory existence
    const simulatedDirs = [
      '/project/src',
      '/project/src/components',
      '/project/src/services',
      '/project/node_modules',
      '/project/node_modules/react',
      '/project/node_modules/lodash',
    ];
    
    return simulatedDirs.includes(path);
  }

  private async readJsonFile(path: string): Promise<any> {
    // Simulate reading package.json files
    const simulatedPackageJsons: Record<string, any> = {
      '/project/node_modules/react/package.json': {
        name: 'react',
        version: '18.2.0',
        main: 'index.js',
        types: 'index.d.ts'
      },
      '/project/node_modules/lodash/package.json': {
        name: 'lodash',
        version: '4.17.21',
        main: 'lodash.js',
        types: 'index.d.ts'
      }
    };
    
    return simulatedPackageJsons[path] || {};
  }

  // 📊 Get resolution statistics
  getStats() {
    return {
      ...this.resolutionStats,
      averageTime: this.resolutionStats.totalTime / 
        (this.resolutionStats.successful + this.resolutionStats.failed)
    };
  }
}

// 🎮 Usage example
const resolutionDemo = async (): Promise<void> => {
  const resolver = new ModuleResolutionDemo();
  
  const compilerOptions = {
    baseUrl: '/project/src',
    paths: {
      '@/*': ['*'],
      '@components/*': ['components/*'],
      '@services/*': ['services/*'],
      '@utils/*': ['utils/*']
    }
  };
  
  // 📁 Test relative import
  await resolver.resolveModule(
    './UserService',
    '/project/src/components/UserProfile.ts',
    compilerOptions
  );
  
  // 🗺️ Test path-mapped import
  await resolver.resolveModule(
    '@components/Button',
    '/project/src/pages/HomePage.ts',
    compilerOptions
  );
  
  // 📦 Test node module import
  await resolver.resolveModule(
    'react',
    '/project/src/App.tsx',
    compilerOptions
  );
  
  // 📊 Display statistics
  console.log('📊 Resolution Statistics:', resolver.getStats());
};

💡 Module Resolution Strategies

TypeScript supports two main module resolution strategies:

• 📦 Node.js Resolution: Mimics Node.js module resolution (default)
• 📁 Classic Resolution: Legacy strategy (rarely used)

// 🌟 Understanding different resolution strategies
// This affects how TypeScript locates modules

// 📦 Node.js Resolution Strategy (moduleResolution: "node")
// For import { UserService } from './UserService'
// 1. Look for ./UserService.ts
// 2. Look for ./UserService.tsx
// 3. Look for ./UserService.d.ts
// 4. Look for ./UserService/package.json (with "main" field)
// 5. Look for ./UserService/index.ts
// 6. Look for ./UserService/index.tsx
// 7. Look for ./UserService/index.d.ts

// 📁 Classic Resolution Strategy (moduleResolution: "classic")
// For import { UserService } from './UserService'
// 1. Look for ./UserService.ts
// 2. Look for ./UserService.d.ts
// For non-relative imports, walks up directory tree

// 🎯 Advanced resolution configuration examples
interface CompilerOptionsExample {
  // 🔧 Module resolution strategy
  moduleResolution: 'node' | 'classic';
  
  // 📍 Base directory for resolving non-relative modules
  baseUrl: string;
  
  // 🗺️ Path mapping for custom module resolution
  paths: Record<string, string[]>;
  
  // 🔍 Additional root directories
  rootDirs: string[];
  
  // 📄 Type acquisition settings
  typeRoots: string[];
  types: string[];
  
  // 🔧 Module format settings
  module: 'commonjs' | 'amd' | 'system' | 'umd' | 'es6' | 'es2015' | 'es2020' | 'esnext' | 'none';
  
  // 📦 Node modules type resolution
  esModuleInterop: boolean;
  allowSyntheticDefaultImports: boolean;
  
  // 🔍 Resolution tracing
  traceResolution: boolean;
}

// 🎮 Comprehensive tsconfig.json examples
const nodeResolutionConfig: CompilerOptionsExample = {
  moduleResolution: 'node',
  baseUrl: './src',
  paths: {
    // 🎯 Absolute imports
    '@/*': ['*'],
    '@components/*': ['components/*'],
    '@services/*': ['services/*'],
    '@utils/*': ['utils/*'],
    '@types/*': ['types/*'],
    
    // 🔧 Specific library mappings
    'react': ['../node_modules/@types/react'],
    'lodash': ['../node_modules/@types/lodash'],
    
    // 🌍 Environment-specific paths
    '@env': ['environments/production'],
    '@config': ['config/production.config']
  },
  rootDirs: [
    './src',
    './generated',
    './types'
  ],
  typeRoots: [
    './node_modules/@types',
    './types',
    './src/types'
  ],
  types: [
    'node',
    'jest',
    'react',
    'react-dom'
  ],
  module: 'es2020',
  esModuleInterop: true,
  allowSyntheticDefaultImports: true,
  traceResolution: false // Set to true for debugging
};

// 🔧 Debugging module resolution
class ModuleResolutionDebugger {
  // 🐛 Common resolution issues and solutions
  static diagnosticIssues = {
    'cannot-find-module': {
      description: 'Module not found error',
      commonCauses: [
        'Incorrect file path',
        'Missing file extension in import',
        'Package not installed',
        'Incorrect path mapping configuration',
        'Case sensitivity issues',
        'Missing index file'
      ],
      solutions: [
        'Check file path and spelling',
        'Verify package is installed',
        'Check tsconfig.json paths configuration',
        'Use --traceResolution flag for debugging',
        'Ensure index files exist for directory imports'
      ]
    },
    
    'path-mapping-not-working': {
      description: 'Custom path mappings not resolving',
      commonCauses: [
        'Incorrect baseUrl configuration',
        'Wrong path pattern syntax',
        'Missing files at mapped locations',
        'IDE not recognizing tsconfig paths'
      ],
      solutions: [
        'Verify baseUrl is set correctly',
        'Check path pattern uses correct glob syntax',
        'Restart TypeScript service in IDE',
        'Use relative imports as fallback'
      ]
    },
    
    'type-definitions-missing': {
      description: 'Type definitions not found',
      commonCauses: [
        'Missing @types package',
        'Incorrect typeRoots configuration',
        'Types not included in compilation',
        'Declaration files not generated'
      ],
      solutions: [
        'Install @types/* packages',
        'Configure typeRoots correctly',
        'Add types to include array',
        'Enable declaration generation'
      ]
    }
  };

  // 🔍 Analyze resolution configuration
  static analyzeConfiguration(tsConfig: any): {
    issues: string[];
    suggestions: string[];
    optimizations: string[];
  } {
    const issues: string[] = [];
    const suggestions: string[] = [];
    const optimizations: string[] = [];

    const options = tsConfig.compilerOptions || {};

    // ✅ Check moduleResolution
    if (!options.moduleResolution) {
      suggestions.push('Consider explicitly setting moduleResolution to "node"');
    }

    // ✅ Check baseUrl and paths consistency
    if (options.paths && !options.baseUrl) {
      issues.push('paths configuration requires baseUrl to be set');
    }

    // ✅ Check for performance optimizations
    if (options.paths && Object.keys(options.paths).length > 20) {
      optimizations.push('Consider reducing number of path mappings for better performance');
    }

    // ✅ Check typeRoots configuration
    if (!options.typeRoots && !options.types) {
      suggestions.push('Consider configuring typeRoots or types for better IntelliSense');
    }

    // ✅ Check for modern module settings
    if (options.module === 'commonjs' && options.target !== 'es5') {
      optimizations.push('Consider using es2020 or esnext module format for better tree shaking');
    }

    return { issues, suggestions, optimizations };
  }

  // 🔧 Generate resolution trace
  static generateResolutionTrace(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any
  ): string[] {
    const trace: string[] = [];
    
    trace.push(`======== Resolving module '${importSpecifier}' from '${fromFile}'. ========`);
    trace.push(`Module resolution kind is not specified, using '${compilerOptions.moduleResolution || 'node'}'.`);
    
    if (importSpecifier.startsWith('./') || importSpecifier.startsWith('../')) {
      trace.push(`Loading module as file / folder, candidate module location '${importSpecifier}', target file type 'TypeScript'.`);
      trace.push(`File '${fromFile.replace(/[^/]+$/, '')}${importSpecifier}.ts' exist - use it as a name resolution result.`);
    } else {
      trace.push(`Loading module '${importSpecifier}' from 'node_modules' folder, target file type 'TypeScript'.`);
      
      if (compilerOptions.baseUrl && compilerOptions.paths) {
        trace.push(`'baseUrl' option is set to '${compilerOptions.baseUrl}', using this value to resolve non-relative module name '${importSpecifier}'.`);
        trace.push(`'paths' option is specified, looking for a pattern to match module name '${importSpecifier}'.`);
      }
    }
    
    trace.push(`======== Module name '${importSpecifier}' was successfully resolved. ========`);
    
    return trace;
  }

  // 📊 Performance analysis
  static analyzeResolutionPerformance(stats: {
    totalResolutions: number;
    averageTime: number;
    cacheHitRate: number;
    failureRate: number;
  }): {
    performance: 'excellent' | 'good' | 'poor';
    recommendations: string[];
  } {
    const recommendations: string[] = [];
    let performance: 'excellent' | 'good' | 'poor' = 'excellent';

    if (stats.averageTime > 10) {
      performance = 'poor';
      recommendations.push('Consider reducing complexity of path mappings');
      recommendations.push('Enable module caching in your build tool');
      recommendations.push('Use fewer deeply nested directories');
    } else if (stats.averageTime > 5) {
      performance = 'good';
      recommendations.push('Consider optimizing path mappings');
    }

    if (stats.cacheHitRate < 0.7) {
      recommendations.push('Improve module caching strategy');
      recommendations.push('Consider using incremental compilation');
    }

    if (stats.failureRate > 0.1) {
      recommendations.push('Review module resolution configuration');
      recommendations.push('Check for typos in import statements');
      recommendations.push('Ensure all dependencies are properly installed');
    }

    return { performance, recommendations };
  }
}

🎉 Conclusion

Congratulations! You’ve mastered the art of TypeScript module resolution! 🔍

🎯 What You’ve Learned

• 🔍 Resolution Algorithms: Understanding how TypeScript finds modules
• 📦 Node.js Strategy: The most common resolution approach
• 🗺️ Path Mapping: Custom module resolution with baseUrl and paths
• 🔧 Configuration: Optimizing tsconfig.json for better resolution
• 🐛 Debugging: Troubleshooting common resolution issues

🚀 Key Benefits

• ⚡ Faster Development: Quick understanding of import errors
• 🎯 Better Organization: Optimal project structure for resolution
• 🔧 Efficient Debugging: Quick resolution issue diagnosis
• 📦 Smooth Imports: Understanding when and how imports work
• 🚀 Build Optimization: Faster compilation through better configuration

🔥 Best Practices Recap

1. 📁 Consistent Structure: Organize files for predictable resolution
2. 🗺️ Smart Path Mapping: Use paths for cleaner, more maintainable imports
3. 🔧 Explicit Configuration: Set moduleResolution explicitly
4. 🐛 Trace Resolution: Use —traceResolution for debugging
5. 📊 Monitor Performance: Keep track of resolution times and optimization

You’re now equipped to understand exactly how TypeScript finds your modules and how to structure your projects for optimal development experience! 🌟

Happy coding, and may your modules always resolve successfully! 🔍✨