useImportExtensions (since v1.8.0)

Diagnostic Category: lint/nursery/useImportExtensions

Enforce file extensions for relative imports.

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

Tooling also benefits from explicit file extensions, because they do not need to guess which file to resolve.

The rule checks static imports and dynamic imports calls such as import() and require().

To ensure that Visual Studio Code adds the file extension when it automatically imports a variable, you may set javascript.preferences.importModuleSpecifierEnding and typescript.preferences.importModuleSpecifierEnding to the desired file extension.

Examples

Invalid

import "./foo";

code-block.js:1:8 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ import "./foo";
      │        ^^^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1   │ - import·"./foo";
      1 │ + import·"./foo.js";
    2 2 │

import "./foo/";

code-block.js:1:8 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ import "./foo/";
      │        ^^^^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1 │ import·"./foo/index.js";
      │               ++++++++

import "../";

code-block.js:1:8 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ import "../";
      │        ^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1 │ import·"../index.js";
      │            ++++++++

import "../.";

code-block.js:1:8 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ import "../.";
      │        ^^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1   │ - import·"../.";
      1 │ + import·"../index.js";
    2 2 │

import("./foo");

code-block.js:1:8 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ import("./foo");
      │        ^^^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1   │ - import("./foo");
      1 │ + import("./foo.js");
    2 2 │

require("./foo");

code-block.js:1:9 lint/nursery/useImportExtensions  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Add a file extension for relative imports.
  
  > 1 │ require("./foo");
      │         ^^^^^^^
    2 │ 
  
  ℹ Explicit import improves compatibility with browsers and makes file resolution in tooling faster.
  
  ℹ Unsafe fix: Add potential import extension .js.
  
    1   │ - require("./foo");
      1 │ + require("./foo.js");
    2 2 │

Valid

import "biome";

import "./foo.js";

import "./bar/index.js";

import("./foo.js");

require("./foo.js");

Options

Use the options to specify the correct import extensions for your project based on the linted file extension. These mappings will override the rule’s default logic.

Currently, Biome determines the import extension based on the inspected file extension. The suggestedExtensions option works as a map, where the key is the source file extension and the value should provide two possible mappings for imports:

module is used for module imports that start with a lower-case character, e.g. foo.js
component is used for component files that start with an upper-case character, e.g. Foo.jsx (which is a common convention for React JSX)

For example, if you want .ts files to import other modules as .js (or .jsx), you should configure the following options in your Biome config:

{
    "//": "...",
    "options": {
        "suggestedExtensions": {
            "ts": {
                "module": "js",
                "component": "jsx"
            }
        }
    }
}

Caveats

If you are using TypeScript, TypeScript version 5.0 and later is required, also make sure to enable allowImportingTsExtensions=true in your tsconfig.json.

Rule does not yet check filesystem for file type. It tries to guess which extension it should add based on the file extension of the current file and the import path. When applying the suggested fix, make sure to verify that the file type is correct.