eslint-plugin-import

What is eslint-plugin-import?

The eslint-plugin-import npm package is a plugin for ESLint that provides linting functionality for ES2015+ (ES6+) import/export syntax, and helps prevent issues with misspelling of file paths and import names, as well as other common mistakes in import declaration.

What are eslint-plugin-import's main functionalities?

Static analysis

This feature checks for modules that are imported but cannot be resolved to a file in the file system. It helps in catching typos or incorrect paths in import statements.

"rules": { "import/no-unresolved": "error" }

Helpful warnings

This feature ensures that named imports correspond to a named export in the remote file. It prevents importing names that do not exist in the exported module.

"rules": { "import/named": "error" }

Style guide enforcement

This feature enforces a convention in module import order, making the code more readable and organized by ensuring a consistent order of imports.

"rules": { "import/order": "error" }

Preventing issues

This feature prevents exporting mutable bindings which can create hard to follow bugs due to their values being changed by other modules.

"rules": { "import/no-mutable-exports": "error" }

Forbidding certain imports

This feature allows you to restrict which files can be imported in a given folder, helping to enforce separation of concerns within your codebase.

"rules": { "import/no-restricted-paths": "error" }

Other packages similar to eslint-plugin-import

eslint-plugin-node

This package provides similar linting rules for Node.js specific features and best practices. It includes rules that prevent issues related to file paths and imports, but is more focused on Node.js environment compatibility.

eslint-plugin-modules

This is another plugin that focuses on linting ECMAScript 2015+ module syntax. However, it is not as widely used or as comprehensive as eslint-plugin-import.

eslint-plugin-requirejs

This plugin is designed for linting RequireJS import syntax. It is similar in that it helps with module import issues, but it is specific to the RequireJS AMD module loader, whereas eslint-plugin-import is for ES2015+ module syntax.

README

eslint-plugin-import

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

IF YOU ARE USING THIS WITH SUBLIME: see the bottom section for important info.

Current support:

• Ensure imports point to a file/module that can be resolved. (no-unresolved)
• Ensure named imports correspond to a named export in the remote file. (named)
• Ensure a default export is present, given a default import. (default)
• Ensure imported namespaces contain dereferenced properties as they are dereferenced. (namespace)
• Report assignments (at any scope) to imported names/namespaces. (no-reassign)
• Report CommonJS require of ES6 module. (no-require, off by default)
• Report use of exported name as identifier of default export (no-named-as-default)

Settings:

• Global (from .eslintrc/settings)
  • import.ignore: a list of regex strings that will be ignored across all rules.
  • import.resolve: a passthrough to resolve's opts parameter for resolve.sync.

• on individual rules:
  • all/relative-only indicate whether a given rule should attempt to parse/lint absolute (all) vs. just relative paths (relative-only).

By default, all rules use relative-only behavior, with the exception of no-unresolved.

You can set this behavior on a rule-by-rule basis from your .eslintrc when configuring rule levels, as follows:

plugins:
  - import

rules:
  import/default: [2, 'all']
  import/no-unresolved: [2, 'relative-only']  # needed since default for this rule is 'all'
  import/no-require: 1  # uses default 'relative-only'

settings:
  import.ignore:
    # any imported module path matching one of these patterns will not be parsed
  	- '^common'
  	- 'es5'

  import.resolve:

    extensions:
      # if unset, default is just '.js', but it must be re-added explicitly if set
      - .js
      - .jsx
      - .es6
      - .coffee

    paths:
      # an array of absolute paths which will also be searched
      # think NODE_PATH
      - /usr/local/share/global_modules

Installation

npm install eslint-plugin-import -g

or if you manage ESLint as a dev dependency:

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

Rules

no-unresolved

Ensures an imported module can be resolved to a module on the local filesystem, as defined by standard Node require.resolve behavior.

Will attempt to resolve from one or more paths from the resolve.root shared setting, i.e.

---
settings:
  resolve.root: 'src'

or

  resolve.root:
    - 'src'
    - 'lib'

Paths may be absolute or relative to the package root (i.e., where your package.json is).

named

Verifies that all named imports are part of the set of named exports in the referenced module.

default

If a default import is requested, this rule will report if there is no default export in the imported module.

namespace

Enforces names exist at the time they are dereferenced, when imported as a full namespace (i.e. import * as foo from './foo'; foo.bar(); will report if bar is not exported by ./foo.).

Will report at the import declaration if there are no exported names found.

Also, will report for computed references (i.e. foo["bar"]()).

Implementation note: currently, this rule does not check for possible redefinition of the namespace in an intermediate scope. Adherence to either import/no-reassign or the ESLint no-shadow rule for namespaces will prevent this from being a problem.

no-reassign

Reports on assignment to an imported name (or a member of an imported namespace). Will also report shadowing (i.e. redeclaration as a variable, function, or parameter);

no-require

Reports require of modules with ES named or default exports. Off by default.

no-named-as-default

Reports use of an exported name as the locally imported name of a default export.

Given:

// foo.js
export default 'foo';
export const bar = 'baz';

...this would be valid:

import foo from './foo.js';

...and this would be reported:

// message: Using exported name 'bar' as identifier for default export.
import bar from './foo.js';

Rationale: using an exported name as the name of the default export is likely

• misleading: others familiar with foo.js probably expect the name to be foo
• a mistake: only needed to import bar and forgot the brackets (the case that is prompting this)

Debugging

no-errors

Reports on errors in the attempt to parse the imported module for exports. Primarily useful for determining why imports are not being reported properly by the other rules. Pass include-messages as an option to include error descriptions in the report.

SublimeLinter-eslint

Recently, SublimeLinter-eslint introduced a change to support .eslintignore files which altered the way file paths are passed to ESLint when linting during editing.

See roadhump/SublimeLinter-eslint#58 for more details, but essentially, you may find you need to add the following to a .sublimelinterrc file:

{
  "linters": {
    "eslint": {
      "args": ["--stdin-filename", "@"]
    }
  }
}

I also found that I needed to set rc_search_limit to null, which removes the file hierarchy search limit when looking up the directory tree for .sublimelinterrc:

In Package Settings / SublimeLinter / User Settings:

{
  "user": {
    "rc_search_limit": null
  }
}

I believe this defaults to 3, so you may not need to alter it depending on your project folder max depth.