source: trip-planner-front/node_modules/resolve-url-loader/README.md@ fa375fe

Last change on this file since fa375fe was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit
  • Property mode set to 100644
File size: 6.6 KB
RevLine 
[6a3a178]1# Resolve URL Loader
2
3[![NPM](https://nodei.co/npm/resolve-url-loader.png)](https://www.npmjs.com/package/resolve-url-loader)
4
5This **webpack loader** allows you to have a distributed set SCSS files and assets co-located with those SCSS files.
6
7## Do you organise your SCSS and assets by feature?
8
9Where are your assets?
10
11* ✅ I want my assets all over the place, next to my SCSS files.
12* ❌ My assets are in a single directory.
13
14How complicated is your SASS?
15
16* ✅ I have a deep SASS composition with partials importing other partials.
17* ✅ My asset paths are constructed by functions or `@mixin`s.
18* ❌ I have a single SCSS file. The asset paths are just explicit in that.
19
20What asset paths are you using?
21
22* ✅ Fully relative `url(./foo.png)` or `url(foo.png)`
23* ❌ Root relative `url(/foo.png)`
24* ❌ Relative to some package or webpack root `url(~stuff/foo.png`)
25* ❌ Relative to some variable which is your single asset directory `url($variable/foo.png)`
26
27What webpack errors are you getting?
28
29* ✅ Webpack can't find the relative asset `foo.png` 😞
30* ❌ Webpack says it doesn't have a loader for `fully/resolved/path/foo.png` 😕
31
32If 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**.
33
34If 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. 🤷
35
36Once webpack resolves your assets (even if it complains about loading them) then this loading is working correctly. 👍
37
38## What's the problem with SASS?
39
40When 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()`.
41
42To illustrate here are 3 simple examples of SASS and Webpack _without_ `resolve-url-loader`.
43
44[![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)
45
46The first 2 cases are trivial and work fine. The asset is specified in the root SCSS file and Webpack finds it.
47
48But any practical SASS composition will have nested SCSS files, as in the 3rd case. Here Webpack cannot find the asset.
49
50```
51Module not found: Can't resolve './cool.png' in '/absolute/path/.../my-project/src/styles.scss'
52```
53
54The path we present to Webpack really needs to be `./subdir/cool.png` but we don't want to write that in our SCSS. 😒
55
56Luckily we can use `resolve-url-loader` to do the **url re-writing** and make it work. 😊🎉
57
58With functions and mixins and multiple nesting it gets more complicated. Read more detail in [how the loader works](docs/how-it-works.md). 🤓
59
60## Getting started
61
62> **Upgrading?** the [changelog](CHANGELOG.md) shows how to migrate your webpack config.
63
64### Install
65
66via npm
67
68```bash
69npm install resolve-url-loader --save-dev
70```
71
72via yarn
73
74```bash
75yarn add resolve-url-loader --dev
76```
77
78### Configure Webpack
79
80The typical use case is `resolve-url-loader` between `sass-loader` and `css-loader`.
81
82**⚠️ IMPORTANT**
83* **source-maps required** for loaders preceding `resolve-url-loader` (regardless of `devtool`).
84* Always use **full loader package name** (don't omit `-loader`) otherwise you can get errors that are hard to debug.
85
86
87``` javascript
88rules: [
89 {
90 test: /\.scss$/,
91 use: [
92 ...
93 {
94 loader: 'css-loader',
95 options: {...}
96 }, {
97 loader: 'resolve-url-loader',
98 options: {...}
99 }, {
100 loader: 'sass-loader',
101 options: {
102 sourceMap: true,
103 sourceMapContents: false
104 }
105 }
106 ]
107 },
108 ...
109]
110```
111
112## Options
113
114The loader should work without options but use these as required.
115
116| option | type | default | | description |
117|-------------|----------------------------|-----------------------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
118| `sourceMap` | boolean | `false` | | Generate an outgoing source-map. |
119| `removeCR` | boolean | `true` Windows OS<br/>`false` otherwise | | Convert orphan CR to whitespace.<br/>See known issues below. |
120| `debug` | boolean | `false` | | Display debug information. |
121| `silent` | boolean | `false` | | Do **not** display warnings or deprecation messages. |
122| `root` | string | _unset_ | | Similar to the (now defunct) option in `css-loader`.<br/>This string, possibly empty, is prepended to absolute URIs.<br/>Absolute URIs are only processed if this option is set. |
123| `join` | function | _inbuilt_ | advanced | Custom join function.<br/>Use custom javascript to fix asset paths on a per-case basis.<br/>Refer to the [advanced features](docs/advanced-features.md) docs. |
124| `engine` | `'rework'`<br/>`'postcss'` | `'postcss'` | deprecated | The css parser engine.<br/>Using this option produces a deprecation warning. |
125
126## Limitations
127
128### Compatiblity
129
130Tested `macOS` and `Windows`.
131
132All `webpack2`-`webpack4` with contemporaneous loaders/plugins using `node 8.9`. And `webpack5` with latest loaders/plugins using `node 10.0`.
133
134Refer to `test` directory for full webpack configurations as used in automated tests.
135
136Some edge cases with `libsass` on `Windows` (see [troubleshooting](docs/troubleshooting.md) docs).
137
138### Known issues
139
140Read the [troubleshooting](docs/troubleshooting.md) docs before raising an issue.
Note: See TracBrowser for help on using the repository browser.