Resolve URL Loader

Webpack loader that resolves relative paths in url() statements based on the original source file.

Use in conjunction with the sass-loader and specify your asset url() relative to the scss file in question. This loader will use the source-map from the SASS compiler to locate the original file and write a more complete path for your asset. Subsequent build steps can then locate your asset for processing.

Usage

Plain CSS works fine:

var css = require('!css!resolve-url!./file.css');

or using sass-loader:

var css = require('!css!resolve-url!sass?sourceMap!./file.scss');

Use in tandem with the style-loader to compile sass and to add the css rules to your document:

require('!style!css!resolve-url!./file.css');

and

require('!style!css!resolve-url!sass?sourceMap!./file.scss');

Source maps required

Note that source maps must be enabled on any preceding loader. In the above example we use sass?sourceMap.

In some use cases (no preceding transpiler) there will be no incoming source map. Therefore we do not warn if the source-map is missing.

Apply via webpack config

It is preferable to adjust your webpack.config so to avoid having to prefix every require() statement:

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

Options

absolute Forces the url() to be resolved to an absolute path. This is considered bad practice so only do it if you know what you are doing.
sourceMap Generate a source-map.
silent Do not display warnings on CSS syntax error.
fail Syntax errors will result in an error.

How it works

The incoming source-map is used to resolve the original file. This is necessary where there was some preceding transpile step such as SASS. A rework process is then run on incoming css.

Each url() statement that implies an asset triggers a file search using node fs operations. The search begins relative to the original file and usually the asset is found immediately. However in some cases there is no immediate match (cough bootstrap cough) and we so we start searching both deeper and shallower from the starting directory. The search will continue while within the project directory and until a package.json or bower.json file is encountered.