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:
Module systems:
Style guide:
Installation
npm install eslint-plugin-import -g
or if you manage ESLint as a dev dependency:
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
plugins:
- import
rules:
import/no-unresolved: [2, {commonjs: true, amd: true}]
import/named: 2
import/namespace: 2
import/default: 2
import/export: 2
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
:
settings:
import/resolver: foo
module.exports = {
settings: {
'import/resolver': {
foo: { someConfig: value }
}
}
}
- with a full npm module name, like
my-awesome-npm-module
:
settings:
import/resolver: 'my-awesome-npm-module'
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:
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
export
s.
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 export
s are found.
In practice, this means rules other than no-unresolved
will not report on any
import
s with (absolute) paths matching this pattern, unless export
s 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
- \.coffee$
- \.(scss|less|css)$
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'
that would otherwise be unresolved. To avoid this, you may provide electron
as a
core module:
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:
settings:
import/cache:
lifetime: ∞
Otherwise, set some integer, and cache entries will be evicted after that many seconds have elapsed:
settings:
import/cache:
lifetime: 5
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.