resolve-url-loader

What is resolve-url-loader?

The resolve-url-loader package is a webpack loader that resolves relative paths in url() statements based on the original source file. This is particularly useful when dealing with source maps and pre-processors like Sass, as it allows assets referenced in CSS to be correctly found and bundled by webpack.

What are resolve-url-loader's main functionalities?

Resolving relative URLs

This feature allows resolve-url-loader to adjust relative paths in url() statements so that they point to the correct location in a webpack build. The code sample shows how to include resolve-url-loader in a webpack configuration.

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

Source map support

resolve-url-loader can handle source maps, which is essential for debugging processed stylesheets like those written in Sass. The code sample demonstrates how to enable source map support in webpack loaders, including resolve-url-loader.

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

Other packages similar to resolve-url-loader

file-loader

file-loader resolves import/require() on a file into a url and emits the file into the output directory. It's similar to resolve-url-loader in that it helps with asset management, but it doesn't resolve relative URLs based on the original source file.

url-loader

url-loader works like file-loader but can return a DataURL if the file is smaller than a byte limit. It's similar to resolve-url-loader as it deals with URLs in CSS and other files, but it doesn't specifically address the resolution of relative paths.

README

Resolve URL Loader

This webpack loader allows you to have a distributed set SCSS files and assets co-located with those SCSS files.

Do you organise your SCSS and assets by feature?

Where are your assets?

• ✅ I want my assets all over the place, next to my SCSS files.
• ❌ My assets are in a single directory.

How complicated is your SASS?

• ✅ I have a deep SASS composition with partials importing other partials.
• ✅ My asset paths are constructed by functions or @mixins.
• ❌ I have a single SCSS file. The asset paths are just explicit in that.

What asset paths are you using?

• ✅ Fully relative url(./foo.png) or url(foo.png)
• ❌ Root relative url(/foo.png)
• ❌ Relative to some package or webpack root url(~stuff/foo.png)
• ❌ Relative to some variable which is your single asset directory url($variable/foo.png)

What webpack errors are you getting?

• ✅ Webpack can't find the relative asset foo.png 😞
• ❌ Webpack says it doesn't have a loader for fully/resolved/path/foo.png 😕

If you can tick at least 1 item in all of these questions then use this loader. It will allow webpack to find assets with fully relative paths.

If for any question you can't tick any items then webpack should be able to already find your assets. You don't need this loader. 🤷

Once webpack resolves your assets (even if it complains about loading them) then this loading is working correctly. 👍

What's the problem with SASS?

When you use fully relative paths in url() statements then Webpack expects to find those assets next to the root SCSS file, regardless of where you specify the url().

To illustrate here are 3 simple examples of SASS and Webpack without resolve-url-loader.

The first 2 cases are trivial and work fine. The asset is specified in the root SCSS file and Webpack finds it.

But any practical SASS composition will have nested SCSS files, as in the 3rd case. Here Webpack cannot find the asset.

Module not found: Can't resolve './cool.png' in '/absolute/path/.../my-project/src/styles.scss'

The path we present to Webpack really needs to be ./subdir/cool.png but we don't want to write that in our SCSS. 😒

Luckily we can use resolve-url-loader to do the url re-writing and make it work. 😊🎉

With functions and mixins and multiple nesting it gets more complicated. Read more detail in how the loader works. 🤓

Getting started

Upgrading? the changelog shows how to migrate your webpack config.

Install

via npm

npm install resolve-url-loader --save-dev

via yarn

yarn add resolve-url-loader --dev

Configure Webpack

The typical use case is resolve-url-loader between sass-loader and css-loader.

⚠️ IMPORTANT

• source-maps required for loaders preceding resolve-url-loader (regardless of devtool).
• Always use full loader package name (don't omit -loader) otherwise you can get errors that are hard to debug.

rules: [
  {
    test: /\.scss$/,
    use: [
      ...
      {
        loader: 'css-loader',
        options: {...}
      }, {
        loader: 'resolve-url-loader',
        options: {...}
      }, {
        loader: 'sass-loader',
        options: {
          sourceMap: true,
          sourceMapContents: false
        }
      }
    ]
  },
  ...
]

Options

The loader should work without options but use these as required.

option	type	default		description
sourceMap	boolean	false		Generate an outgoing source-map.
removeCR	boolean	true Windows OS false otherwise		Convert orphan CR to whitespace. See known issues below.
debug	boolean	false		Display debug information.
silent	boolean	false		Do not display warnings or deprecation messages.
root	string	unset		Similar to the (now defunct) option in css-loader. This string, possibly empty, is prepended to absolute URIs. Absolute URIs are only processed if this option is set.
join	function	inbuilt	advanced	Custom join function. Use custom javascript to fix asset paths on a per-case basis. Refer to the advanced features docs.
engine	'rework' 'postcss'	'postcss'	deprecated	The css parser engine. Using this option produces a deprecation warning.

Limitations

Compatiblity

Tested macOS and Windows.

All webpack2-webpack4 with contemporaneous loaders/plugins using node 8.9. And webpack5 with latest loaders/plugins using node 10.0.

Refer to test directory for full webpack configurations as used in automated tests.

Some edge cases with libsass on Windows (see troubleshooting docs).

Known issues

Read the troubleshooting docs before raising an issue.