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

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

bholloway

resolve-url-loader

  "description": "Webpack loader that resolves relative paths in url() statements based on the original source file",

    "url": "git+https://github.com/bholloway/resolve-url-loader.git",

    "directory": "packages/resolve-url-loader"

    "url": "https://github.com/bholloway/resolve-url-loader/issues"

  "homepage": "https://github.com/bholloway/resolve-url-loader/tree/master/packages/resolve-url-loader",

  "homepage": "https://github.com/bholloway/resolve-url-loader/tree/v4-maintenance/packages/resolve-url-loader",

[![NPM](https://nodei.co/npm/resolve-url-loader.png)](https://www.npmjs.com/package/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?

* ✅ I want my assets all over the place, next to my SCSS files.

* ❌ My assets are in a single directory.

* ✅ I have a deep SASS composition with partials importing other partials.

* ✅ My asset paths are constructed by functions or `@mixin`s.

* ❌ I have a single SCSS file. The asset paths are just explicit in that.

* ✅ Fully relative `url(./foo.png)` or `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)`

* ✅ 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. 👍

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 basic problem](https://raw.githubusercontent.com/bholloway/resolve-url-loader/master/packages/resolve-url-loader/docs/basic-problem.svg)](docs/basic-problem.svg)

[![the basic problem](https://raw.githubusercontent.com/bholloway/resolve-url-loader/v4-maintenance/packages/resolve-url-loader/docs/basic-problem.svg)](docs/basic-problem.svg)

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](docs/how-it-works.md). 🤓

> **Upgrading?** the [changelog](CHANGELOG.md) shows how to migrate your webpack config.

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

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

* **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.

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

|-------------|----------------------------|-----------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

| `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. |

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/troubleshooting.md) docs).

Read the [troubleshooting](docs/troubleshooting.md) docs before raising an issue.

		{
		"name": "resolve-url-loader",
		"version": "4.0.0-beta.2",
		"version": "4.0.0",
		"description": "Webpack loader that resolves relative paths in url() statements based on the original source file",
		@@ -28,3 +28,3 @@ "main": "index.js",
		},
		"homepage": "https://github.com/bholloway/resolve-url-loader/tree/master/packages/resolve-url-loader",
		"homepage": "https://github.com/bholloway/resolve-url-loader/tree/v4-maintenance/packages/resolve-url-loader",
		"engines": {
		@@ -31,0 +31,0 @@ "node": ">=8.9"

Fixed alerts

Improved metrics

		@@ -44,3 +44,3 @@ # Resolve URL Loader

		[![the basic problem](https://raw.githubusercontent.com/bholloway/resolve-url-loader/master/packages/resolve-url-loader/docs/basic-problem.svg)](docs/basic-problem.svg)
		[![the basic problem](https://raw.githubusercontent.com/bholloway/resolve-url-loader/v4-maintenance/packages/resolve-url-loader/docs/basic-problem.svg)](docs/basic-problem.svg)

		@@ -47,0 +47,0 @@ The first 2 cases are trivial and work fine. The asset is specified in the root SCSS file and Webpack finds it.