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
  • Performance

Why

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

• https://github.com/import-js/eslint-plugin-import/issues/1479
• https://github.com/import-js/eslint-plugin-import/issues/2108
• https://github.com/import-js/eslint-plugin-import/issues/2111

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

eslint-plugin-import now claims in https://github.com/un-ts/eslint-plugin-import-x/issues/170 that it will accept BREAKING CHANGES. However, still nothing is happening: https://github.com/import-js/eslint-plugin-import/pull/3091.

eslint-plugin-import refuses to support the exports feature, and the maintainer even locked the feature request issue https://github.com/import-js/eslint-plugin-import/issues/1810 to prevent future discussion. In the meantime, eslint-plugin-import-x now provides first-party support for the exports feature https://github.com/un-ts/eslint-plugin-import-x/pull/209, 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): https://github.com/un-ts/eslint-plugin-import-x/issues/235.

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 || ^10.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

If you're type-checking your eslint.config.js, but you aren't using typescript-eslint for some reason (you really should consider it), you need to also install @typescript-eslint/utils, because the type definitions depend on it.

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.

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	Forbid import statements with CommonJS module.exports.				🔧
no-nodejs-modules	Forbid Node.js builtin modules.
unambiguous	Forbid potentially ambiguous parse goal (script vs. module).

Performance

Name	Description	💼	⚠️	🚫	🔧	💡	❌
avoid-barrel-files	Forbid authoring of barrel files.
avoid-importing-barrel-files	Forbid importing barrel files.
avoid-namespace-import	Forbid namespace imports.
avoid-re-export-all	Forbid re-exporting * from a module.

Static analysis

Name	Description	💼	⚠️	🚫	🔧	💡	❌
default	Ensure a default export is present, given a default import.	❗ ❗ ☑️ ☑️
named	Ensure named imports correspond to a named export in the remote file.	❗ ❗ ☑️ ☑️		⌨️ ⌨️
namespace	Ensure imported namespaces contain dereferenced properties as they are dereferenced.	❗ ❗ ☑️ ☑️
no-absolute-path	Forbid import of modules using absolute paths.				🔧
no-cycle	Forbid a module from importing a module with a dependency path back to itself.

Style guide

Name	Description	💼	⚠️	🚫	🔧	💡	❌
consistent-type-specifier-style	Enforce or ban the use of inline type-only markers for named imports.				🔧
dynamic-import-chunkname	Enforce a leading comment with the webpackChunkName for dynamic imports.					💡
exports-last	Ensure all exports appear after other statements.
extensions	Ensure consistent use of file extension within the import path.				🔧	💡
first	Ensure all imports appear before other statements.				🔧

Resolvers

With the advent of module bundlers and the current state of modules and module syntax specs, it's not always obvious where import x from 'module' should look to find the file behind module.

Up through v0.10ish, this plugin has directly used substack's resolve plugin, which implements Node's import behavior. This works pretty well in most cases.

However, webpack allows a number of things in import module source strings that Node does not, such as loaders (import 'file!./whatever') and a number of aliasing schemes, such as externals: mapping a module id to a global name at runtime (allowing some modules to be included more traditionally via script tags).

In the interest of supporting both of these, v0.11 introduces resolvers.

Currently Node and webpack resolution have been implemented, but the resolvers are just npm packages, so third party packages are supported (and encouraged!).

You can reference resolvers in several ways (in order of precedence):

• as a conventional eslint-import-resolver name, like eslint-import-resolver-foo:

import-x/resolver-next

[!warning]

Only available in the new flat config system. If you are using the legacy config system, please use import-x/resolver instead.

// eslint.config.js

import { createTypeScriptImportResolver } from 'eslint-import-resolver-typescript'
import { createNodeResolver } from 'eslint-plugin-import-x'

export default [
  {
    settings: {
      'import-x/resolver-next': [
        createTypeScriptImportResolver(/* Your override options go here */),
        createNodeResolver(/* Your override options go here */),
      ],
    },
  },
]

import-x/resolver

# .eslintrc.yml
settings:
  # uses 'eslint-import-resolver-foo':
  import-x/resolver: foo

// .eslintrc.js
module.exports = {
  settings: {
    'import-x/resolver': {
      foo: { someConfig: value },
    },
  },
}

• with a full npm module name, like my-awesome-npm-module:

# .eslintrc.yml
settings:
  import-x/resolver: 'my-awesome-npm-module'

// .eslintrc.js
module.exports = {
  settings: {
    'import-x/resolver': {
      'my-awesome-npm-module': { someConfig: value },
    },
  },
}

• with a filesystem path to resolver, defined in this example as a computed property name:

// .eslintrc.js
module.exports = {
  settings: {
    'import-x/resolver': {
      [path.resolve('../../../my-resolver')]: { someConfig: value },
    },
  },
}

• use the import or require syntax to directly import the resolver object:

// .eslintrc.mjs
import * as tsResolver from 'eslint-import-resolver-typescript'

export default {
  settings: {
    'import-x/resolver': {
      name: 'tsResolver', // required, could be any string you like
      // enable: false, // optional, defaults to true
      // optional, options to pass to the resolver https://github.com/import-js/eslint-import-resolver-typescript#configuration
      options: {
        bun: true, // optional, resolve Bun modules https://github.com/import-js/eslint-import-resolver-typescript#bun
      },
      resolver: tsResolver, // required, the resolver object
    },
  },
}

// .eslintrc.cjs
const tsResolver = require('eslint-import-resolver-typescript')

module.exports = {
  settings: {
    'import-x/resolver': {
      name: 'tsResolver', // required, could be any string you like
      // enable: false, // optional, defaults to true
      // optional, options to pass to the resolver https://github.com/import-js/eslint-import-resolver-typescript#configuration
      options: {
        bun: true, // optional, resolve Bun modules https://github.com/import-js/eslint-import-resolver-typescript#bun
      },
      resolver: tsResolver, // required, the resolver object
    },
  },
}

Relative paths will be resolved relative to the source's nearest package.json or the process's current working directory if no package.json is found.

If you are interesting in writing a resolver, see the spec for more details.

Settings

You may set the following settings in your .eslintrc:

import-x/extensions

A list of file extensions that will be parsed as modules and inspected for exports.

This defaults to ['.js'], unless you are using the react shared config, in which case it is specified as ['.js', '.jsx']. Despite the default, if you are using TypeScript (without the plugin:import-x/typescript config described above) you must specify the new extensions (.ts, and also .tsx if using React).

"settings": {
  "import-x/extensions": [
    ".js",
    ".jsx"
  ]
}

If you require more granular extension definitions, you can use:

"settings": {
  "import-x/resolver": {
    "node": {
      "extensions": [
        ".js",
        ".jsx"
      ]
    }
  }
}

Note that this is different from (and likely a subset of) any import-x/resolver extensions settings, which may include .json, .coffee, etc. which will still factor into the no-unresolved rule.

Also, the following import-x/ignore patterns will overrule this list.

import-x/ignore

A list of RegExp or RegExp pattern strings that, if matched by a path, will not report the matching module if no exports are found. In practice, this means rules other than no-unresolved will not report on any imports with (absolute filesystem) paths matching this pattern.

no-unresolved has its own ignore setting.

settings:
  import-x/ignore:
    - \.coffee$ # fraught with parse errors
    - \.(scss|less|css)$ # can't parse unprocessed CSS modules, either

import-x/core-modules

An array of additional modules to consider as "core" modules--modules that should be considered resolved but have no path on the filesystem. Your resolver may already define some of these (for example, the Node resolver knows about fs and path), so you need not redefine those.

For example, Electron exposes an electron module:

import 'electron' // without extra config, will be flagged as unresolved!

that would otherwise be unresolved. To avoid this, you may provide electron as a core module:

# .eslintrc.yml
settings:
  import-x/core-modules: [electron]

In Electron's specific case, there is a shared config named electron that specifies this for you.

Contribution of more such shared configs for other platforms are welcome!

import-x/external-module-folders

An array of folders. Resolved modules only from those folders will be considered as "external". By default - ["node_modules"]. Makes sense if you have configured your path or webpack to handle your internal paths differently and want to consider modules from some folders, for example bower_components or jspm_modules, as "external".

This option is also useful in a monorepo setup: list here all directories that contain monorepo's packages and they will be treated as external ones no matter which resolver is used.

If you are using yarn PnP as your package manager, add the .yarn folder and all your installed dependencies will be considered as external, instead of internal.

Each item in this array is either a folder's name, its subpath, or its absolute prefix path:

• jspm_modules will match any file or folder named jspm_modules or which has a direct or non-direct parent named jspm_modules, e.g. /home/me/project/jspm_modules or /home/me/project/jspm_modules/some-pkg/index.js.

• packages/core will match any path that contains these two segments, for example /home/me/project/packages/core/src/utils.js.

• /home/me/project/packages will only match files and directories inside this directory, and the directory itself.

Please note that incomplete names are not allowed here so components won't match bower_components and packages/ui won't match packages/ui-utils (but will match packages/ui/utils).

import-x/parsers

A map from parsers to file extension arrays. If a file extension is matched, the dependency parser will require and use the map key as the parser instead of the configured ESLint parser. This is useful if you're inter-op-ing with TypeScript directly using webpack, for example:

# .eslintrc.yml
settings:
  import-x/parsers:
    '@typescript-eslint/parser': [.ts, .tsx]

In this case, @typescript-eslint/parser must be installed and require-able from the running eslint module's location (i.e., install it as a peer of ESLint).

This is currently only tested with @typescript-eslint/parser (and its predecessor, typescript-eslint-parser) but should theoretically work with any moderately ESTree-compliant parser.

It's difficult to say how well various plugin features will be supported, too, depending on how far down the rabbit hole goes. Submit an issue if you find strange behavior beyond here, but steel your heart against the likely outcome of closing with wontfix.

import-x/resolver and import-x/resolver-next

See resolvers.

import-x/cache

Settings for cache behavior. Memoization is used at various levels to avoid the copious amount of fs.statSync/module parse calls required to correctly report errors.

For normal eslint console runs, the cache lifetime is irrelevant, as we can strongly assume that files should not be changing during the lifetime of the linter process (and thus, the cache in memory)

For long-lasting processes, like eslint_d or eslint-loader, however, it's important that there be some notion of staleness.

If you never use eslint_d or eslint-loader, you may set the cache lifetime to Infinity and everything should be fine:

# .eslintrc.yml
settings:
  import-x/cache:
    lifetime: ∞ # or Infinity

Otherwise, set some integer, and cache entries will be evicted after that many seconds have elapsed:

# .eslintrc.yml
settings:
  import-x/cache:
    lifetime: 5 # 30 is the default

import-x/internal-regex

A regex for packages should be treated as internal. Useful when you are utilizing a monorepo setup or developing a set of packages that depend on each other.

By default, any package referenced from import-x/external-module-folders will be considered as "external", including packages in a monorepo like yarn workspace or lerna environment. If you want to mark these packages as "internal" this will be useful.

For example, if your packages in a monorepo are all in @scope, you can configure import-x/internal-regex like this

# .eslintrc.yml
settings:
  import-x/internal-regex: ^@scope/

Sponsors and Backers

Sponsors

1stG	RxTS	UnTS

Backers

1stG	RxTS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © JounQin@1stG.me

Star History