eslint-plugin-import

eslint-plugin-import extends ESLint with a comprehensive rule set purpose-built for ES2015+ module syntax. Instead of waiting for a bundler or runtime error, it statically resolves every import and export in a codebase to catch unresolved file paths, misspelled or missing named exports, circular dependency chains, and inconsistent module-system usage (mixing CommonJS require with ES import) directly in the editor or CI.

The plugin ships 46 rules organized into helpful-warnings, module-systems, static-analysis, and style-guide categories, plus ready-made configs (recommended, errors, warnings, react, react-native, electron, typescript) for both legacy .eslintrc and modern flat-config setups. It underpins the import/order, no-unresolved, and no-cycle rules relied on by the vast majority of JavaScript and TypeScript projects that enforce import hygiene.

What You Get

• 46 rules spanning helpful warnings, module-system enforcement, static analysis, and style-guide conventions
• Both legacy .eslintrc configs and modern ESLint 9 flat configs, including recommended/errors/warnings presets
• Framework-specific configs for React, React Native, Electron, and TypeScript projects
• A pluggable module-resolver system (Node, Webpack, TypeScript) so import resolution matches your actual build setup
• Static export-map analysis that understands re-exports, namespace imports, and cross-file export tracking

Common Use Cases

• Catching typo’d or renamed import paths and missing named exports at lint time instead of at runtime
• Enforcing a consistent, alphabetized or grouped import order across a large team codebase via import/order
• Detecting circular dependency chains between modules with import/no-cycle before they cause subtle bugs
• Preventing accidental mixing of CommonJS require() and ES import syntax in the same codebase
• Flagging unused exports across a project with no-unused-modules during dead-code cleanup

Under The Hood

Architecture

The plugin’s core is an export-resolution engine, not the rules themselves: src/exportMap/builder.js and src/exportMap/index.js construct an ExportMap per source file, walking export/import declarations, re-exports (export * from), and namespace exports into a cached graph of namespace, reexports, dependencies, and imports maps. Rules like no-cycle and named consume this graph rather than re-parsing files themselves, and a strongly-connected-components pass (src/scc.js) reduces cycle-detection from exponential re-traversal to near-linear graph analysis. Each of the 46 rules under src/rules/ is a self-contained ESLint rule module registered centrally in src/index.js, which also assembles the legacy and flat-config bundles (configs/flatConfigs) so the same rule implementations back both config formats.

Tech Stack

Written in ES2015+ JavaScript and compiled with Babel (babel-cli, babel-preset-airbnb) to a lib/ output consumed via the main/types fields in package.json. Module resolution is delegated to separate eslint-import-resolver-node/-webpack/-typescript packages and shared through eslint-module-utils, keeping the resolver strategy swappable per project. Peer-dependency support spans ESLint 2 through 10, and dependencies like is-core-module, tsconfig-paths, and semver handle Node builtin detection, TS path-mapping, and version-range peer checks respectively.

Code Quality

Testing is extensive: 343 test files under tests/src mirror the src/ rule and core-module structure one-to-one, run via Mocha with nyc coverage instrumentation and Babel-registered ES module support. posttest chains ESLint self-linting, an eslint-doc-generator consistency check, and markdownlint across all docs, and CI runs a matrix across multiple ESLint major versions (eslint-8+.yml, eslint-old.yml) plus a native-WSL workflow — unusually thorough version-compatibility coverage for an ESLint plugin.

API Design Each of the 46 rules is documented individually under docs/rules/, auto-generated into the README’s category tables (Helpful warnings, Module systems, Static analysis, Style guide) with emoji badges showing which preset config enables, warns, or disables it, and whether it’s auto-fixable. Rules are consumed the standard ESLint way (add to plugins/extends, no custom API surface to learn), and three maintained example projects (examples/legacy, examples/flat, examples/v9) demonstrate working configurations for each ESLint config generation, lowering the setup barrier for the plugin’s actual audience: package.json editors, not application code callers.