resolve-url-loader

5.0.0 verified Sat Apr 25 auth: no javascript

Webpack loader that rewrites relative paths in url() statements based on the original source file. v5.0.0 (stable) requires node>=12, webpack>=4, and uses postcss@8. Removed the deprecated rework engine entirely. Key differentiator: it fixes the mismatch between Sass partial location and CSS output location for feature-based project structures, enabling co-located assets with partials. Actively maintained with automated tests. Alternatives like css-loader's url handling or other loaders are less targeted.

Common errors

error Module build failed (from ./node_modules/resolve-url-loader/index.js): Error: resolve-url-loader: Cannot resolve original source file ↓

cause Source maps are missing or incorrect from preceding loaders (e.g., sass-loader without sourceMap: true).

fix

Enable sourceMap: true on sass-loader and css-loader.

error Error: resolve-url-loader: engine option is deprecated. Use postcss parser instead. ↓

cause Using engine: 'rework' in version 4 or 5.

fix

Remove the engine option (default is postcss in v5) or set engine: 'postcss'.

error Module build failed (from ./node_modules/resolve-url-loader/index.js): Error: resolve-url-loader: Cannot find module 'rework' ↓

cause Using engine: 'rework' in version 5 where rework dependency was removed.

fix

Remove engine option or set to 'postcss'.

error Error: resolve-url-loader: root option must be a string ↓

cause Passing a non-string value (e.g., boolean or number) to root option.

fix

Set root to a string (e.g., '' for empty) or remove the option.

Warnings

breaking Version 5 removed the 'rework' engine (deprecated in v4). Engine option only accepts 'postcss' now. ↓

fix Remove engine option or set to 'postcss'.

breaking Version 5 requires node>=12 and webpack>=4. ↓

fix Update node and webpack to meet requirements.

deprecated Option 'engine' is deprecated in v4 but still usable with 'rework'. In v5 it was removed. ↓

fix Migrate to postcss engine by setting engine: 'postcss'.

gotcha Source maps are required for loaders preceding resolve-url-loader, regardless of devtool setting. ↓

fix Enable sourceMap option on sass-loader and css-loader.

gotcha On Windows, absolute paths in url() may fail. Set root: '' option to fix them before css-loader. ↓

fix Set root: '' in resolve-url-loader options.

breaking Version 4 changed the meaning of the 'root' option. Previously it limited file search; now it is the base path for absolute URIs. ↓

fix Update your configuration: if you used root for file search, remove it; if you need base path for absolute URIs, set root accordingly.

Install

npm install resolve-url-loader

yarn add resolve-url-loader

pnpm add resolve-url-loader

Imports

resolve-url-loader

wrong

const resolveUrlLoader = require('resolve-url-loader')

correct

import resolveUrlLoader from 'resolve-url-loader'

CommonJS require works too (package supports both).

default import

wrong

const { default: resolveUrlLoader } = require('resolve-url-loader')

correct

import resolveUrlLoader from 'resolve-url-loader'

Default import is the loader itself; named exports don't exist.

webpack config

wrong

module.exports = { module: { loaders: [{ test: /\.scss$/, loader: 'style-loader!css-loader!resolve-url-loader!sass-loader' }] } }

correct

module.exports = { module: { rules: [{ test: /\.scss$/, use: ['style-loader','css-loader','resolve-url-loader','sass-loader'] }] } }

Use `use` array with full loader names; avoid legacy `loaders` syntax and exclamation marks.

Quickstart

Shows a typical webpack configuration using resolve-url-loader between sass-loader and css-loader with source maps enabled.

// webpack.config.js
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'resolve-url-loader',
            options: {
              sourceMap: true, // required for preceding loaders
              engine: 'postcss', // default since v5
              root: '' // optional, for absolute paths
            }
          },
          {
            loader: 'sass-loader',
            options: {
              sourceMap: true
            }
          }
        ]
      }
    ]
  },
  devtool: 'source-map'
};

// src/index.scss
@import 'features/foo';

// src/features/_foo.scss
.foo { background: url(bar.png); }

// src/features/bar.png exists
// Without resolve-url-loader, css-loader would look for src/bar.png (wrong)
// With resolve-url-loader, url(bar.png) becomes url(features/bar.png) (correct)