eslint-plugin-import-x

eslint-plugin-import-x

This plugin intends to support linting of ES2015+ (ES6+) import/export syntax, and prevent issues with misspelling of file paths and import names. All the goodness that the ES2015+ static module syntax intends to provide, marked up in your editor.

It started as a fork of [eslint-plugin-import] using [get-tsconfig] to replace [tsconfig-paths] and heavy [typescript] under the hood, making it faster, through less heavy dependency on Typescript, and cleaner dependencies altogether.

eslint-plugin-i is now eslint-plugin-import-x

TOC

• Why
• Differences
• Installation
• Configuration (new: eslint.config.*)
  • JS example
  • Typescript example
  • As a standalone ESLint plugin
  • Using defineConfig
• Configuration (legacy: .eslintrc*)
  • TypeScript
• Rules
  • Helpful warnings
  • Module systems
  • Static analysis
  • Style guide
• Resolvers
  • import-x/resolver-next
  • import-x/resolver
• Settings
  • import-x/extensions
  • import-x/ignore
  • import-x/core-modules
  • import-x/external-module-folders
  • import-x/parsers
  • import-x/resolver and import-x/resolver-next
  • import-x/cache
  • import-x/internal-regex
• Sponsors and Backers
  • Sponsors
  • Backers
• Changelog
• License
• Star History

Why

Many issues cannot be fixed easily without API changes. For example, see:

[eslint-plugin-import] refused to accept BREAKING CHANGES for these issues, so we had to fork it.

[eslint-plugin-import] now claims in that it will accept BREAKING CHANGES. However, still nothing is happening: .

[eslint-plugin-import] refuses to support the exports feature, and the maintainer even locked the feature request issue to prevent future discussion. In the meantime, eslint-plugin-import-x now provides first-party support for the exports feature , which will become the default in the next major version (v5).

We haven't resolved all the issues yet, but we are working on them, which could happen in the next major version (v5): .

Differences

So what are the differences from eslint-plugin-import exactly?

• we target Node ^18.18.0 || ^20.9.0 || >=21.1.0 + ESLint ^8.57.0 || ^9.0.0, while eslint-plugin-import targets Node >=4 and ESLint ^2 || ^3 || ^4 || ^5 || ^6 || ^7.2.0 || ^8 || ^9
• we don't depend on old and outdated dependencies, so we have 16 dependencies compared to 117 dependencies for eslint-plugin-import
• eslint-plugin-import uses tsconfig-paths + typescript itself to load tsconfigs while we use the single get-tsconfig instead, which is much faster and cleaner
• eslint-plugin-import uses [resolve] which doesn't support the exports field in package.json while we build our own rust-based resolver [unrs-resolver] instead, which is feature-rich and way more performant.
• Our v3 resolver interface shares a single resolver instance by default which is used all across resolving chains so it would benefit from caching and memoization out-of-the-box
• ...

The list could be longer in the future, but we don't want to make it too long here. Hope you enjoy and let's get started.

Installation

# inside your project's working tree
npm install eslint-plugin-import-x --save-dev

Configuration (new: eslint.config.*)

From v8.21.0, ESLint announced a new config system. In the new system, .eslintrc* is no longer used. eslint.config.* would be the default config file name.

JS example

import js from '@eslint/js'
import { importX } from 'eslint-plugin-import-x'

export default [js.configs.recommended, importX.flatConfigs.recommended]

Typescript example

You have to install eslint-import-resolver-typescript:

npm install eslint-import-resolver-typescript --save-dev

import js from '@eslint/js'
import { importX } from 'eslint-plugin-import-x'
import tsParser from '@typescript-eslint/parser'

export default [
  js.configs.recommended,
  importX.flatConfigs.recommended,
  importX.flatConfigs.typescript,
  {
    files: ['**/*.{js,mjs,cjs,jsx,mjsx,ts,tsx,mtsx}'],
    languageOptions: {
      parser: tsParser,
      ecmaVersion: 'latest',
      sourceType: 'module',
    },
    rules: {
      'import-x/no-dynamic-require': 'warn',
      'import-x/no-nodejs-modules': 'warn',
    },
  },
]

[!NOTE] A complete list of available configuration can be found in config/flat folders

As a standalone ESLint plugin

import { importX } from 'eslint-plugin-import-x'

export default [
  {
    plugins: {
      'import-x': importX,
    },
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
    },
    rules: {
      'import-x/no-dynamic-require': 'warn',
      'import-x/no-nodejs-modules': 'warn',
    },
  },
]

Using defineConfig

import { importX } from 'eslint-plugin-import-x'
import { defineConfig } from 'eslint/config'

export default defineConfig([
  {
    plugins: {
      'import-x': importX,
    },
    extends: ['import-x/flat/recommended'],
    rules: {
      'import-x/no-dynamic-require': 'warn',
    },
  },
])

Configuration (legacy: .eslintrc*)

[!TIP] If your eslint is >=8.23.0, you're 100% ready to use the new config system. See dedicated section above.

[!NOTE] All rules are off by default. However, you may configure them manually in your .eslintrc.(yml|json|js), or extend one of the canned configs:

extends:
  - eslint:recommended
  - plugin:import-x/recommended
  # alternatively, 'recommended' is the combination of these two rule sets:
  - plugin:import-x/errors
  - plugin:import-x/warnings

# or configure manually:
plugins:
  - import-x

rules:
  import-x/no-unresolved: [2, { commonjs: true, amd: true }]
  import-x/named: 2
  import-x/namespace: 2
  import-x/default: 2
  import-x/export: 2
  # etc...

TypeScript

You may use the following snippet or assemble your own config using the granular settings described below it.

[!WARNING] Make sure you have installed [@typescript-eslint/parser] and [eslint-import-resolver-typescript] which are used in the following configuration.

extends:
  - eslint:recommended
  - plugin:import-x/recommended
  # the following lines do the trick
  - plugin:import-x/typescript
settings:
  import-x/resolver:
    # You will also need to install and configure the TypeScript resolver
    # See also https://github.com/import-js/eslint-import-resolver-typescript#configuration
    typescript: true

Rules

Configurations enabled in.
⚠️ Configurations set to warn in.
Configurations disabled in.
❗ Set in the errors configuration.
❗ Set in the flat/errors configuration.
☑️ Set in the flat/recommended configuration.
⌨️ Set in the flat/typescript configuration.
Set in the flat/warnings configuration.
☑️ Set in the recommended configuration.
⌨️ Set in the typescript configuration.
Set in the warnings configuration.
Automatically fixable by the --fix CLI option.
Manually fixable by editor suggestions.
❌ Deprecated.

Helpful warnings

Name	Description		⚠️				❌
export	Forbid any invalid exports, i.e. re-export of the same name.	❗ ❗ ☑️ ☑️
no-deprecated	Forbid imported names marked with @deprecated documentation tag.
no-empty-named-blocks	Forbid empty named import blocks.
no-extraneous-dependencies	Forbid the use of extraneous packages.
no-mutable-exports	Forbid the use of mutable exports with var or let.
no-named-as-default	Forbid use of exported name as identifier of default export.		☑️ ☑️
no-named-as-default-member	Forbid use of exported name as property of default export.		☑️ ☑️
no-rename-default	Forbid importing a default export by a different name.
no-unused-modules	Forbid modules without exports, or exports without matching import in another module.

Module systems

Name	Description		⚠️				❌
no-amd	Forbid AMD require and define calls.
no-commonjs	Forbid CommonJS require calls and module.exports or exports.*.
[no-import-module-exports](docs/rules/no-import-module-exports.