Webpack's module resolution rules

Webpack, as the core of modern front-end build tools, has a module resolution mechanism that directly affects the correctness of the bundling results and the development experience. Understanding the module resolution rules helps developers precisely control dependency reference paths, avoid common "Module not found" errors, and lays the foundation for advanced configurations such as aliases and extension handling.

Core Process of Resolution Rules

When Webpack encounters a statement like require('./module'), the resolution process is divided into three stages:

1. Path Type Determination: Distinguish between relative paths (./), absolute paths (/), or module names (react).
2. File System Location: Attempt to match physical files or directories.
3. Extension Completion: Automatically try adding suffixes like .js, .json, etc.

The specific resolution order is as follows:

// Example: require('./utils')
[
  '/project/src/utils.js',       // Directly match the full filename
  '/project/src/utils.json',     // Try different extensions
  '/project/src/utils/index.js', // Directory index file
  '/project/src/utils/package.json' // Via the `main` field in package.json
]

Path Resolution Details

Relative Paths and Absolute Paths

Paths starting with ./ or ../ are treated as relative paths and resolved based on the current file's directory:

// src/app.js
import util from './lib/util'; 
// Resolves to: /project/src/lib/util.js

Absolute paths are resolved directly from the filesystem root (usually requiring additional configuration):

// Requires resolve.modules configuration
import config from '/absolute/config';

Module Name Resolution

Non-relative module names trigger module resolution. Webpack's default lookup order is:

1. Check aliases configured in resolve.alias.
2. Look for node_modules directories.
3. Read the main or module field in package.json.

// Example: require('lodash')
[
  '/project/node_modules/lodash.js',
  '/project/node_modules/lodash/index.js',
  '/project/node_modules/lodash/package.json'
]

Key Configuration Options

resolve.extensions

Controls the order of automatic extension attempts. The default value is:

module.exports = {
  resolve: {
    extensions: ['.js', '.json', '.wasm']
  }
};

To add .ts support:

extensions: ['.ts', '.js', '.json']

resolve.modules

Specifies the module search directories. By default, only node_modules is searched:

modules: ['node_modules', 'src/shared']

resolve.alias

Creates path aliases, often used to simplify long paths:

alias: {
  '@components': path.resolve(__dirname, 'src/components/'),
  'old-lib': 'new-lib' // Replace deprecated libraries
}

Advanced Resolution Scenarios

Directory Index Files

When a path points to a directory, index.js is looked up by default:

components/
  Button/
    index.js  // require('./components/Button')
    style.css

The default filename can be modified via resolve.mainFiles:

mainFiles: ['main', 'index']  // Try main.js first

Package Entry Override

Control the priority of package.json entry fields via resolve.mainFields:

mainFields: ['browser', 'module', 'main']

Symbolic Link Handling

Enable resolve.symlinks to determine whether to follow symbolic links:

symlinks: false  // Do not resolve the actual path of symbolic links

Custom Resolution Logic

Add custom resolvers via resolve.plugins, such as implementing specific prefix handling:

class CustomResolver {
  apply(resolver) {
    resolver.hooks.resolve.tapAsync('CustomResolver', (request, callback) => {
      if (request.request.startsWith('#')) {
        const newPath = path.join(__dirname, 'internal', request.request.slice(1));
        callback(null, {
          path: newPath,
          query: request.query,
          file: true
        });
      } else {
        callback();
      }
    });
  }
}

Common Issue Solutions

Duplicate Module Bundling

When multiple versions of a module appear, force a specific version via resolve.alias:

alias: {
  'react': path.resolve('./node_modules/react')
}

TypeScript Path Mapping

Requires synchronization between tsconfig.json and Webpack:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

// webpack.config.js
alias: {
  '@': path.resolve(__dirname, 'src/')
}

Browser Environment Simulation

For using Node.js modules in the browser, configure resolve.fallback:

resolve: {
  fallback: {
    "fs": false,
    "path": require.resolve("path-browserify")
  }
}