ESLint Import Resolver - Webpack

ESLint Import Resolver - Webpack is a module resolution plugin for eslint-plugin-import that integrates with webpack configurations. It enables ESLint to understand webpack's module resolution strategy including aliases, extensions, and custom resolve configurations, ensuring import/export rules work correctly with webpack-based projects.

Package Information

• Package Name: eslint-import-resolver-webpack
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install eslint-import-resolver-webpack --save-dev

Core Imports

const resolver = require("eslint-import-resolver-webpack");

// Access the main resolver function
const { resolve } = resolver;

// Check interface version
const { interfaceVersion } = resolver;

Basic Usage

The resolver is typically configured in your ESLint configuration file rather than used directly in code:

# .eslintrc.yml
settings:
  import/resolver: webpack  # Use default webpack.config.js

Or with custom configuration:

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config: 'webpack.dev.config.js'
      env:
        NODE_ENV: 'development'

Architecture

The resolver operates by:

1. Config Discovery: Locates webpack configuration files using filesystem traversal and interpret library
2. Webpack Integration: Dynamically requires webpack and enhanced-resolve from your project
3. Resolution Strategy: Uses webpack's enhanced-resolve with your configuration to resolve module paths
4. Caching: Implements LRU caching for performance optimization
5. Version Compatibility: Supports both webpack 1.x and 2.x+ with appropriate resolver creation

Capabilities

Resolver Interface

The main resolver interface that ESLint plugin import uses to resolve module paths. The resolver automatically strips webpack loaders and resource queries from the source parameter before processing.

Input Processing

The resolver preprocesses the source parameter as follows:

1. Loader Stripping: Removes webpack loaders (e.g., 'style-loader!./file.css' becomes './file.css')
2. Query Stripping: Removes resource queries (e.g., './file.js?query' becomes './file.js')

This ensures that only the actual module path is resolved, without webpack-specific syntax.

/**
 * Interface version for eslint-plugin-import compatibility
 */
exports.interfaceVersion = 2;

/**
 * Resolve module paths using webpack configuration
 * @param {string} source - The module to resolve (e.g., './some-module'). Webpack loaders (e.g., 'style-loader!./file.css') and resource queries (e.g., './file.js?query') are automatically stripped.
 * @param {string} file - The importing file's full path
 * @param {ResolverSettings} settings - Webpack configuration settings
 * @returns {ResolverResult} Resolution result with found status and path
 */
exports.resolve = function(source, file, settings);

Configuration Settings

Configuration options for customizing resolver behavior.

interface ResolverSettings {
  /** Path to webpack config file or config object */
  config?: string | WebpackConfig;
  /** Current working directory to resolve webpack from (defaults to directory containing config path) */
  cwd?: string;
  /** Zero-based index for selecting specific config from array */
  "config-index"?: number;
  /** Environment variables to pass to webpack config function */
  env?: Record<string, any>;
  /** Arguments to pass to webpack config function (defaults to empty object) */
  argv?: Record<string, any>;
  /** Whether to cache function-based config evaluation (prevents re-evaluation on each resolve call) */
  cache?: boolean;
}

Resolution Result

The result object returned by the resolve function.

interface ResolverResult {
  /** Whether the module was successfully resolved */
  found: boolean;
  /** Resolved absolute path, or null for non-FS resources (e.g., externals, core modules) */
  path: string | null;
}

Webpack Configuration Support

The resolver supports various webpack configuration formats and features:

Configuration Types

• String Path: Relative or absolute path to webpack config file
• Config Object: Direct webpack configuration object
• Function Config: Function that returns webpack configuration (supports env/argv)
• Array Config: Array of configurations (uses first with resolve section or specified index)

Webpack Features

• Aliases: Module path aliases defined in resolve.alias
• Extensions: File extensions to resolve from resolve.extensions
• Module Directories: Custom module search directories
• Main Fields: Package.json entry point fields (browser, module, main)
• Externals: External dependency detection (returns path: null)
• Plugins: Custom resolve plugins (webpack 1.x)

Usage Examples

Basic Configuration

# .eslintrc.yml - Use default webpack.config.js
settings:
  import/resolver: webpack

Custom Config File

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config: 'webpack.dev.config.js'

Multiple Configurations

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config: 'webpack.multiple.config.js'
      config-index: 1  # Use second config

Environment Variables

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config: 'webpack.config.js'
      env:
        NODE_ENV: 'development'
        DEBUG: true

Direct Config Object

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config:
        resolve:
          extensions:
            - .js
            - .jsx
            - .ts
            - .tsx
          alias:
            '@': './src'
            components: './src/components'

Function Config with Caching

# .eslintrc.yml
settings:
  import/resolver:
    webpack:
      config: 'webpack.config.js'
      cache: true  # Cache function config evaluation
      env:
        NODE_ENV: 'production'
      argv:
        mode: 'production'

Error Handling

The resolver handles various error conditions gracefully:

• Missing Config: Uses empty configuration object if no webpack config found
• Invalid Config: Logs errors and throws for debugging
• Resolution Failures: Returns { found: false } for unresolvable modules
• External Modules: Returns { found: true, path: null } for external dependencies
• Core Modules: Returns { found: true, path: null } for Node.js core modules
• Promise Configs: Logs warning and uses empty config (not supported)
• Package Discovery: Throws error if no ancestral package.json found above importing file
• Webpack Loading: Falls back to bundled enhanced-resolve if project webpack unavailable
• Config Compilation: Registers appropriate compilers based on config file extension
• Function Config Errors: Handles synchronous errors in function-based configurations

Compatibility

Webpack Versions

• Webpack 1.x: Uses enhanced-resolve with custom plugin configuration and default package mains ['webpack', 'browser', 'web', 'browserify', ['jam', 'main'], 'main']
• Webpack 2.x+: Uses enhanced-resolve create.sync API with defaults: { unsafeCache: true, modules: ['node_modules'], extensions: ['.js', '.json'], aliasFields: ['browser'], mainFields: ['browser', 'module', 'main'] }

Node.js Versions

• Minimum: Node.js 6+
• Enhanced-resolve: Automatically detects and adapts to version

Peer Dependencies

• eslint-plugin-import: >=1.4.0
• webpack: >=1.11.0

Performance Features

Caching

• Resolver Cache: LRU cache for webpack resolver instances (max 10 entries)
• Function Config Cache: Separate cache for evaluated function configurations
• Cache Keys: Based on config path and webpack configuration object

Optimization

• Lazy Loading: Webpack and enhanced-resolve loaded on-demand
• Bundled Fallback: Uses bundled enhanced-resolve if project webpack unavailable
• Efficient Comparison: Uses lodash isEqual for deep cache key comparison