Resolve

Configure how modules are resolved and located

The resolve configuration changes how modules are resolved. Webpack provides reasonable defaults, but you can customize resolution behavior.

Basic Configuration

webpack.config.js

module.exports = {
  resolve: {
    extensions: ['.js', '.jsx', '.json'],
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
};

Resolve Options

resolve.extensions · string[]

Extensions that are tried when resolving a file.

resolve: {
  extensions: ['.js', '.jsx', '.ts', '.tsx', '.json']
}

Default: ['.js', '.json', '.wasm']

Users can now import modules without adding their extensions:

import App from './App' // resolves to ./App.js, ./App.jsx, etc.

resolve.alias · object | array

Create aliases to import or require certain modules more easily.

resolve: {
  alias: {
    '@': path.resolve(__dirname, 'src'),
    '@components': path.resolve(__dirname, 'src/components'),
    '@utils': path.resolve(__dirname, 'src/utils'),
    // Exact match
    'react$': path.resolve(__dirname, 'node_modules/react/dist/react.min.js')
  }
}

Usage:

import Button from '@/components/Button'
import { format } from '@utils/date'

resolve.modules · string[]

Directories where to look for modules.

resolve: {
  modules: ['node_modules', path.resolve(__dirname, 'src')]
}

Default: ['node_modules']

resolve.mainFields · string[]

Fields in package.json that are checked for the main entry point.

resolve: {
  mainFields: ['browser', 'module', 'main']
}

Default: ['browser', 'module', 'main'] (web), ['module', 'main'] (Node.js)

resolve.mainFiles · string[]

Filenames used when resolving directories.

resolve: {
  mainFiles: ['index', 'main']
}

Default: ['index']

Advanced Options

Conditional Exports

resolve.conditionNames · string[]

Condition names for package.json exports field.

resolve: {
  conditionNames: ['import', 'module', 'browser', 'default']
}

Default: ['webpack', 'production', 'development'] + target-specific

resolve.exportsFields · string[]

Fields in package.json for entry points.

resolve: {
  exportsFields: ['exports']
}

Default: ['exports']

resolve.importsFields · string[]

Fields in package.json for internal package imports.

resolve: {
  importsFields: ['imports']
}

Default: ['imports']

Extension Handling

resolve.extensionAlias · object

Alias one extension to multiple alternatives.

resolve: {
  extensionAlias: {
    '.js': ['.ts', '.js'],
    '.mjs': ['.mts', '.mjs']
  }
}

resolve.enforceExtension · boolean

If true, extensions must be provided.

resolve: {
  enforceExtension: false
}

Default: false

TypeScript Support

resolve.tsconfig · boolean | string | object

Enable TypeScript paths mapping from tsconfig.json.

// Use default tsconfig.json
resolve: {
  tsconfig: true
}

// Specify tsconfig path
resolve: {
  tsconfig: path.resolve(__dirname, 'tsconfig.build.json')
}

// Advanced configuration
resolve: {
  tsconfig: {
    configFile: path.resolve(__dirname, 'tsconfig.json'),
    references: 'auto'
  }
}

Symlinks and Caching

resolve.symlinks · boolean

Resolve symlinks to their real location.

resolve: {
  symlinks: true
}

Default: true

resolve.cache · boolean

Enable caching of module resolutions.

resolve: {
  cache: true
}

Default: true

resolve.cacheWithContext · boolean

Include context in the cache key.

resolve: {
  cacheWithContext: false
}

Default: true

Fallback and Restrictions

resolve.fallback · object

Redirect module requests when normal resolving fails.

resolve: {
  fallback: {
    "crypto": require.resolve("crypto-browserify"),
    "stream": require.resolve("stream-browserify"),
    "path": false // disable polyfill
  }
}

resolve.restrictions · (RegExp | string)[]

Restrict paths that resolve results must match.

resolve: {
  restrictions: [/\/(src|node_modules)\//]
}

resolve.roots · string[]

Directories for server-relative URLs (starting with ’/’).

resolve: {
  roots: [path.resolve(__dirname, 'public')]
}

Path Resolution

resolve.preferAbsolute · boolean

Prefer absolute paths over resolve.roots.

resolve: {
  preferAbsolute: true
}

Default: false

resolve.preferRelative · boolean

Prefer relative resolution over module resolution.

resolve: {
  preferRelative: true
}

Default: false

resolve.fullySpecified · boolean

Require fully specified imports (no extensions/mainFiles).

resolve: {
  fullySpecified: false
}

Default: false

Plugins

resolve.plugins · array

Plugins for the resolver.

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

resolve: {
  plugins: [new TsconfigPathsPlugin()]
}

Package.json Fields

resolve.aliasFields · string[]

Fields in package.json to check for aliases.

resolve: {
  aliasFields: ['browser']
}

Default: ['browser'] (web target)

resolve.descriptionFiles · string[]

Files to read for package description.

resolve: {
  descriptionFiles: ['package.json', 'bower.json']
}

Default: ['package.json']

Resolve Loader

Separate resolve options for loaders:

webpack.config.js

module.exports = {
  resolveLoader: {
    modules: ['node_modules', path.resolve(__dirname, 'loaders')],
    extensions: ['.js', '.json'],
    mainFields: ['loader', 'main']
  }
};

Common Patterns

Aliases for Clean Imports

webpack.config.js

module.exports = {
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@utils': path.resolve(__dirname, 'src/utils'),
      '@styles': path.resolve(__dirname, 'src/styles'),
      '@assets': path.resolve(__dirname, 'src/assets')
    }
  }
};

Usage:

import Button from '@components/Button'
import { api } from '@utils/api'
import logo from '@assets/logo.png'

TypeScript Project

webpack.config.js

module.exports = {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx'],
    tsconfig: path.resolve(__dirname, 'tsconfig.json')
  }
};

Monorepo Setup

webpack.config.js

module.exports = {
  resolve: {
    modules: [
      'node_modules',
      path.resolve(__dirname, '../../node_modules')
    ],
    symlinks: true
  }
};

Node.js Polyfills for Browser

webpack.config.js

module.exports = {
  resolve: {
    fallback: {
      "assert": require.resolve("assert/"),
      "buffer": require.resolve("buffer/"),
      "console": require.resolve("console-browserify"),
      "crypto": require.resolve("crypto-browserify"),
      "http": require.resolve("stream-http"),
      "https": require.resolve("https-browserify"),
      "os": require.resolve("os-browserify/browser"),
      "path": require.resolve("path-browserify"),
      "stream": require.resolve("stream-browserify"),
      "url": require.resolve("url/"),
      "util": require.resolve("util/"),
      "zlib": require.resolve("browserify-zlib")
    }
  }
};

Conditional Package Resolution

webpack.config.js

module.exports = {
  resolve: {
    conditionNames: ['webpack', 'production', 'browser', 'import'],
    mainFields: ['browser', 'module', 'main']
  }
};

Custom Loader Directory

webpack.config.js

module.exports = {
  resolveLoader: {
    modules: [
      'node_modules',
      path.resolve(__dirname, 'custom-loaders')
    ]
  }
};