Analysis and Solutions for Missing File Extension Errors in TypeScript ESLint import/extensions Rule

In TypeScript projects integrated with Node.js/Express, ESLint serves as a widely adopted code quality checking tool. However, many developers encounter a typical error during configuration: Missing file extension "ts" for "./lib/env" import/extensions. This error indicates that file extensions are missing in module imports, specifically targeting TypeScript files (.ts). This article will start from the root cause of the error, progressively analyze the issue, and provide complete solutions.

Error Cause Analysis

The fundamental cause of this error lies in the default settings of the Airbnb ESLint configuration for the import/extensions rule. The Airbnb configuration requires all import statements to explicitly specify file extensions, which is reasonable in JavaScript projects but causes issues in TypeScript projects.

The TypeScript compiler itself can automatically resolve .ts and .tsx file extensions, so explicit extension specification is typically unnecessary during imports. For example, statements like import env from './lib/env' are valid in TypeScript, but the Airbnb ESLint configuration forces them to be written as import env from './lib/env.ts'.

Examining the ESLint configuration file from the problem description, although TypeScript-related extensions are configured in settings.import.extensions, this only informs the ESLint parser that these extensions are valid without changing the checking behavior of the import/extensions rule.

Solution One: Custom import/extensions Rule

The most direct solution is to add a custom configuration for the import/extensions rule in the ESLint configuration's rules section:

"rules": {
  "import/extensions": [
    "error",
    "ignorePackages",
    {
      "js": "never",
      "jsx": "never",
      "ts": "never",
      "tsx": "never"
    }
  ]
}

This configuration means:

• "error": Report violations as errors
• "ignorePackages": Ignore extension checks for packages (modules in node_modules)
• The object configuration specifies handling for different file extensions, where "never" indicates that explicit extension specification is not required

With this configuration, ESLint will no longer require explicit extension specification for .ts and .tsx files during imports, thus resolving the original error.

Solution Two: Using Specialized TypeScript Configuration

Another more elegant solution is to use the eslint-config-airbnb-typescript package specifically designed for TypeScript. This package optimizes the base Airbnb configuration for TypeScript, automatically handling extension-related issues and other TypeScript-specific concerns.

Installation command:

npm install -D eslint-config-airbnb-typescript

Then update the ESLint configuration file:

{
  "extends": [
    "airbnb",
    "airbnb-typescript",
    "plugin:@typescript-eslint/recommended",
    "prettier",
    "prettier/react",
    "plugin:import/errors",
    "plugin:import/warnings",
    "plugin:import/typescript"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json"
  },
  "plugins": ["@typescript-eslint", "prettier", "import"]
}

The advantages of this approach include:

• Automatic handling of all ESLint configuration issues related to TypeScript
• Maintaining consistency with Airbnb code style
• Reducing manual configuration effort and error probability

Configuration Details and Best Practices

When implementing the above solutions, several key configuration points require attention:

Parser Configuration: @typescript-eslint/parser must be used as ESLint's parser, which is the core component for TypeScript and ESLint integration.

Import Parser Configuration: Specify file types handled by the TypeScript parser in settings.import.parsers:

"import/parsers": {
  "@typescript-eslint/parser": [".ts", ".tsx"]
}

Import Resolver Configuration: Configure TypeScript and Node.js resolvers to ensure correct module path resolution:

"import/resolver": {
  "typescript": {
    "directory": "./tsconfig.json"
  },
  "node": {
    "extensions": [".js", ".jsx", ".ts", ".tsx"]
  }
}

These configurations collectively ensure that ESLint correctly understands TypeScript's module system while maintaining code style uniformity.

Version Compatibility Considerations

It's important to note that version compatibility between ESLint plugins and configuration packages is also a significant factor. As mentioned in the reference article, changes in the behavior of the import/extensions rule in eslint-plugin-import v2.19.1 may cause previously working configurations to generate errors.

Therefore, when upgrading ESLint-related dependencies, it is recommended to:

• Carefully read version update logs
• Test first in development environments
• Consider locking versions of critical dependencies

Conclusion

The import/extensions error in ESLint for TypeScript projects is a common but easily solvable issue. By understanding the default behavior of Airbnb configuration and adopting appropriate custom configurations or specialized TypeScript configuration packages, developers can easily resolve this problem. eslint-config-airbnb-typescript is recommended as a long-term solution, as it not only addresses extension issues but also provides a more complete TypeScript development experience.

Proper ESLint configuration not only improves code quality but also significantly enhances development efficiency. It is hoped that the analysis and solutions provided in this article will help developers better utilize the ESLint tool in TypeScript projects.