Resolving ESLint Module Path Resolution Issues in TypeScript Projects

Problem Background and Phenomenon Analysis

In TypeScript development environments, developers frequently encounter ESLint reporting "Unable to resolve path to module" errors. The specific manifestation occurs when using import app from './app' statements in app.spec.ts files, where ESLint fails to recognize the app.ts source file in the same directory, instead expecting to find the compiled app.js file. This phenomenon reveals a mismatch between ESLint's default module resolution mechanism and TypeScript development workflows.

Root Cause Investigation

ESLint's import/no-unresolved rule defaults to using Node.js's module resolution strategy, which is primarily designed for JavaScript files. In standard Node.js environments, module imports typically point to compiled or directly executable file formats like .js, .json, etc. However, during TypeScript development phases, developers work directly with .ts source files that haven't been compiled to JavaScript yet.

While the TypeScript compiler understands import relationships between .ts files, ESLint as an independent code quality tool requires explicit configuration to recognize TypeScript-specific file extensions. This design discrepancy causes workflow interruptions during development: developers must compile TypeScript files after each code modification before passing ESLint static checks, significantly impacting development efficiency.

Solution Implementation

By configuring ESLint's import/resolver settings, developers can extend the file extension range for module resolution. The specific configuration is as follows:

{
  "settings": {
    "import/resolver": {
      "node": {
        "extensions": [".js", ".jsx", ".ts", ".tsx"]
      }
    }
  },
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json"
  }
}

The core of this configuration lies in the extensions array, which explicitly informs ESLint that when resolving module paths, in addition to the default .js and .jsx, it should also attempt .ts and .tsx extensions. When ESLint encounters import statements like import app from './app', it will sequentially try file paths such as ./app.js, ./app.jsx, ./app.ts, ./app.tsx until it finds a matching module file.

Configuration Details and Best Practices

The import/resolver configuration supports multiple resolver types, with the node resolver being the most commonly used option. This resolver is based on Node.js's module resolution algorithm but extends its capabilities through the extensions list to adapt to TypeScript development environment requirements.

In practical projects, it's recommended to arrange file extensions in priority order. Typically, compiled JavaScript files (.js, .jsx) should be listed first, followed by source files (.ts, .tsx). This ordering ensures that in production environments, ESLint prioritizes checking compiled JavaScript files, while in development environments, it can fall back to checking TypeScript source files when compiled files don't exist.

Additionally, the @typescript-eslint/parser and project options in the configuration are equally important. They ensure ESLint can understand TypeScript syntax features and perform more precise code analysis based on path mapping and module resolution settings in tsconfig.json.

Alternative Approach Comparison

Beyond the primary node resolver configuration approach, other viable alternatives exist. One common method involves using the eslint-import-resolver-typescript package, specifically designed for TypeScript projects, which can better handle TypeScript-specific module resolution scenarios like path aliases and namespace imports.

Another approach involves extending ESLint configuration to enable TypeScript-related import rules:

{
  "extends": [
    "plugin:import/errors",
    "plugin:import/warnings",
    "plugin:import/typescript"
  ]
}

This method provides more comprehensive TypeScript import support but may require additional dependency installation and configuration adjustments. In comparison, the direct import/resolver configuration approach is more lightweight and easier to understand, suitable for most project scenarios.

Practical Application Scenarios

Consider a typical TypeScript project structure containing test file app.spec.ts and source file app.ts. Without configured module resolvers, running ESLint reports import errors. After applying the above configuration, ESLint can correctly identify that ./app points to the app.ts file, thereby eliminating error reports.

This configuration is particularly suitable for use in continuous integration environments, ensuring code quality checks can be effectively executed during pre-compilation stages. Developers can run ESLint before committing code to promptly identify potential module import issues without waiting for complete compilation processes.

Conclusion and Future Outlook

By properly configuring ESLint's module resolution mechanism, developers can eliminate "Unable to resolve path to module" errors in TypeScript projects, achieving smoother development experiences. The core solution is simple and effective: extend the node resolver's file extension list to include TypeScript file formats.

As the TypeScript and ESLint ecosystems continue to evolve, more intelligent module resolution solutions may emerge in the future. However, for now, explicit configuration remains a reliable method for ensuring toolchain cooperation. Developers should choose the most appropriate configuration strategy based on specific project requirements, balancing functional completeness with configuration complexity.