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

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

Rules

Static analysis:

• 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)
• Restrict which files can be imported in a given folder (no-restricted-paths)

Helpful warnings:

• Report any invalid exports, i.e. re-export of the same name (export)
• Report use of exported name as identifier of default export (no-named-as-default)
• Report use of exported name as property of default export (no-named-as-default-member)
• Report imported names marked with @deprecated documentation tag (no-deprecated)
• Forbid the use of extraneous packages (no-extraneous-dependencies)
• Forbid the use of mutable exports with var or let. (no-mutable-exports)

Module systems:

• Report CommonJS require calls and module.exports or exports.*. (no-commonjs)
• Report AMD require and define calls. (no-amd)
• No Node.js builtin modules. (no-nodejs-modules)

Style guide:

• Ensure all imports appear before other statements (imports-first)
• Report repeated import of the same module in multiple places (no-duplicates)
• Report namespace imports (no-namespace)
• Ensure consistent use of file extension within the import path (extensions)
• Enforce a convention in module import order (order)
• Enforce a newline after import statements (newline-after-import)
• Prefer a default export if module exports a single name (prefer-default-export)

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

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/errors
  - plugin:import/warnings

# or configure manually:
plugins:
  - import

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

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:

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

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

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

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

// .eslintrc.js
module.exports = {
  settings: {
    'import/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/resolver': {
      [path.resolve('../../../my-resolver')]: { someConfig: value }
    }
  }
}

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/extensions

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

This will default to ['.js'] in the next major revision of this plugin, unless you are using the react shared config, in which case it is specified as ['.js', '.jsx'].

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

Also, import/ignore patterns will overrule this whitelist, so node_modules that end in .js will still be ignored by default.

import/ignore

A list of regex 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) paths matching this pattern, unless exports were found when parsing. This allows you to ignore node_modules but still properly lint packages that define a jsnext:main in package.json (Redux, D3's v4 packages, etc.).

no-unresolved has its own ignore setting.

Note: setting this explicitly will replace the default of node_modules, so you may need to include it in your own list if you still want to ignore it. Example:

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

import/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/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/resolver

See resolvers.

import/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/cache:
    lifetime: ∞  # or Infinity

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

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

SublimeLinter-eslint

SublimeLinter-eslint introduced a change to support .eslintignore files which altered the way file paths are passed to ESLint when linting during editing. This change sends a relative path instead of the absolute path to the file (as ESLint normally provides), which can make it impossible for this plugin to resolve dependencies on the filesystem.

This workaround should no longer be necessary with the release of ESLint 2.0, when .eslintignore will be updated to work more like a .gitignore, which should support proper ignoring of absolute paths via --stdin-filename.

In the meantime, see roadhump/SublimeLinter-eslint#58 for more details and discussion, but essentially, you may find you need to add the following SublimeLinter config to your Sublime project file:

{
    "folders":
    [
        {
            "path": "code"
        }
    ],
    "SublimeLinter":
    {
        "linters":
        {
            "eslint":
            {
                "chdir": "${project}/code"
            }
        }
    }
}

Note that ${project}/code matches the code provided at folders[0].path.

The purpose of the chdir setting, in this case, is to set the working directory from which ESLint is executed to be the same as the directory on which SublimeLinter-eslint bases the relative path it provides.

See the SublimeLinter docs on chdir for more information, in case this does not work with your project.

If you are not using .eslintignore, or don't have a Sublime project file, you can also do the following via a .sublimelinterrc file in some ancestor directory of your code:

{
  "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.