Webpack loader that resolves relative paths in url() statements based on the original source file
$ npm install resolve-url-loader
This webpack loader allows you to have a distributed set SCSS files and assets co-located with those SCSS files.
Where are your assets?
How complicated is your SASS?
@mixin
s.What asset paths are you using?
url(./foo.png)
or url(foo.png)
url(/foo.png)
url(~stuff/foo.png
)url($variable/foo.png)
What webpack errors are you getting?
foo.png
😞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 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. 🤓
via npm
npm install resolve-url-loader --save-dev
via yarn
yarn add resolve-url-loader --dev
The typical use case is resolve-url-loader
between sass-loader
and css-loader
.
⚠️ IMPORTANT
resolve-url-loader
(regardless of devtool
).-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
}
}
]
},
...
]
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 | false |
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. |
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).
Read the troubleshooting docs before raising an issue.
© 2010 - cnpmjs.org x YWFE | Home | YWFE