useImportExtensions

JavaScript (and super languages)

Summary

Rule available since: v1.8.0
Diagnostic Category: lint/correctness/useImportExtensions
This rule has a safe fix.
The default severity of this rule is warning.
This rule belongs to the following domains:
- project

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "correctness": {
5
        "useImportExtensions": "error"
6
      }
7
    }
8
  }
9
}

Description

Enforce file extensions for relative imports.

Browsers, Deno, and Node.js do not natively support importing files without extensions from JavaScript modules. This rule enforces the use of file extensions for relative imports to make the code more consistent — and correct.

In some cases, tooling can also benefit from explicit file extensions, because they do not need to guess which file to resolve.

The rule checks both static imports (import ... from "...") as well as dynamic imports such as import(...) and require(...).

Examples

Invalid

The following examples assume these imports will resolve to a file with an extension. Imports that don’t resolve at all will not trigger a diagnostic.

1
import "./foo";

1
import "./foo/";

1
import "../";

1
import "../.";

1
import("./foo");

1
require("./foo");

Valid

1
import "biome";

1
import "./foo.js";

1
import "./bar/index.js";

1
import("./foo.js");

1
require("./foo.js");

Options

The rule provides the options described below.

extensionMappings

A map of file extensions to their suggested replacements. This allows you to specify custom mappings for import extensions. For example, you can map TypeScript imports to JavaScript extensions.

This is useful if you are bundling your code to JavaScript into a package and want to make sure all imports of TypeScript files use the .js extension instead.

If no mapping is found for a given extension, and the import is missing an extension, the rule will suggest using the actual extension of the resolved file.

Default: {} (empty object)

1
{
2
  "linter": {
3
    "rules": {
4
      "correctness": {
5
        "useImportExtensions": {
6
          "options": {
7
            "extensionMappings": {
8
              "ts": "js",
9
              "tsx": "js"
10
            }
11
          }
12
        }
13
      }
14
    }
15
  }
16
}

forceJsExtensions

Normally, this rule suggests to use the extension of the module that is found in your project. For instance, .ts or .tsx for a TypeScript file. If this option is set to true, the rule will always suggest to use .js regardless of the extension in your project.

This is useful if you use the "module": "node16" setting when building your code with tsc.

Default: false

1
{
2
  "linter": {
3
    "rules": {
4
      "correctness": {
5
        "useImportExtensions": {
6
          "options": {
7
            "forceJsExtensions": true
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

Editor Configuration

If you use Visual Studio Code, you can ensure that it adds the file extension when automatically importing a variable by configuring javascript.preferences.importModuleSpecifierEnding and typescript.preferences.importModuleSpecifierEnding in your settings.

Caveats

If you are using TypeScript, TypeScript version 5.0 or later is required, also make sure to set allowImportingTsExtensions: true in your tsconfig.json.