{"id":20517,"library":"resolve-url-loader","title":"resolve-url-loader","description":"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.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/bholloway/resolve-url-loader","tags":["javascript","webpack","loader","css","normalize","rewrite","resolve","url","sass"],"install":[{"cmd":"npm install resolve-url-loader","lang":"bash","label":"npm"},{"cmd":"yarn add resolve-url-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add resolve-url-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Parsing CSS to find url() statements","package":"postcss","optional":false},{"reason":"Resolving original source positions from source maps","package":"source-map","optional":false}],"imports":[{"note":"CommonJS require works too (package supports both).","wrong":"const resolveUrlLoader = require('resolve-url-loader')","symbol":"resolve-url-loader","correct":"import resolveUrlLoader from 'resolve-url-loader'"},{"note":"Default import is the loader itself; named exports don't exist.","wrong":"const { default: resolveUrlLoader } = require('resolve-url-loader')","symbol":"default import","correct":"import resolveUrlLoader from 'resolve-url-loader'"},{"note":"Use `use` array with full loader names; avoid legacy `loaders` syntax and exclamation marks.","wrong":"module.exports = { module: { loaders: [{ test: /\\.scss$/, loader: 'style-loader!css-loader!resolve-url-loader!sass-loader' }] } }","symbol":"webpack config","correct":"module.exports = { module: { rules: [{ test: /\\.scss$/, use: ['style-loader','css-loader','resolve-url-loader','sass-loader'] }] } }"}],"quickstart":{"code":"// webpack.config.js\nconst path = require('path');\n\nmodule.exports = {\n  entry: './src/index.js',\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: 'bundle.js'\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.scss$/,\n        use: [\n          'style-loader',\n          'css-loader',\n          {\n            loader: 'resolve-url-loader',\n            options: {\n              sourceMap: true, // required for preceding loaders\n              engine: 'postcss', // default since v5\n              root: '' // optional, for absolute paths\n            }\n          },\n          {\n            loader: 'sass-loader',\n            options: {\n              sourceMap: true\n            }\n          }\n        ]\n      }\n    ]\n  },\n  devtool: 'source-map'\n};\n\n// src/index.scss\n@import 'features/foo';\n\n// src/features/_foo.scss\n.foo { background: url(bar.png); }\n\n// src/features/bar.png exists\n// Without resolve-url-loader, css-loader would look for src/bar.png (wrong)\n// With resolve-url-loader, url(bar.png) becomes url(features/bar.png) (correct)","lang":"javascript","description":"Shows a typical webpack configuration using resolve-url-loader between sass-loader and css-loader with source maps enabled."},"warnings":[{"fix":"Remove engine option or set to 'postcss'.","message":"Version 5 removed the 'rework' engine (deprecated in v4). Engine option only accepts 'postcss' now.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update node and webpack to meet requirements.","message":"Version 5 requires node>=12 and webpack>=4.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate to postcss engine by setting engine: 'postcss'.","message":"Option 'engine' is deprecated in v4 but still usable with 'rework'. In v5 it was removed.","severity":"deprecated","affected_versions":">=4.0.0 <5.0.0"},{"fix":"Enable sourceMap option on sass-loader and css-loader.","message":"Source maps are required for loaders preceding resolve-url-loader, regardless of devtool setting.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Set root: '' in resolve-url-loader options.","message":"On Windows, absolute paths in url() may fail. Set root: '' option to fix them before css-loader.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Update your configuration: if you used root for file search, remove it; if you need base path for absolute URIs, set root accordingly.","message":"Version 4 changed the meaning of the 'root' option. Previously it limited file search; now it is the base path for absolute URIs.","severity":"breaking","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Enable sourceMap: true on sass-loader and css-loader.","cause":"Source maps are missing or incorrect from preceding loaders (e.g., sass-loader without sourceMap: true).","error":"Module build failed (from ./node_modules/resolve-url-loader/index.js): Error: resolve-url-loader: Cannot resolve original source file"},{"fix":"Remove the engine option (default is postcss in v5) or set engine: 'postcss'.","cause":"Using engine: 'rework' in version 4 or 5.","error":"Error: resolve-url-loader: engine option is deprecated. Use postcss parser instead."},{"fix":"Remove engine option or set to 'postcss'.","cause":"Using engine: 'rework' in version 5 where rework dependency was removed.","error":"Module build failed (from ./node_modules/resolve-url-loader/index.js): Error: resolve-url-loader: Cannot find module 'rework'"},{"fix":"Set root to a string (e.g., '' for empty) or remove the option.","cause":"Passing a non-string value (e.g., boolean or number) to root option.","error":"Error: resolve-url-loader: root option must be a string"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}