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

Readme

Source

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.

If the asset is not found then the url() statement will not be updated.

Keywords

FAQs

What is resolve-url-loader?

Is resolve-url-loader well maintained?

Last updated on 24 Aug 2015

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install