1 | # loader-utils
|
2 |
|
3 | ## Methods
|
4 |
|
5 | ### `urlToRequest`
|
6 |
|
7 | Converts some resource URL to a webpack module request.
|
8 |
|
9 | > i Before call `urlToRequest` you need call `isUrlRequest` to ensure it is requestable url
|
10 |
|
11 | ```javascript
|
12 | const url = "path/to/module.js";
|
13 |
|
14 | if (loaderUtils.isUrlRequest(url)) {
|
15 | // Logic for requestable url
|
16 | const request = loaderUtils.urlToRequest(url);
|
17 | } else {
|
18 | // Logic for not requestable url
|
19 | }
|
20 | ```
|
21 |
|
22 | Simple example:
|
23 |
|
24 | ```javascript
|
25 | const url = "path/to/module.js";
|
26 | const request = loaderUtils.urlToRequest(url); // "./path/to/module.js"
|
27 | ```
|
28 |
|
29 | #### Module URLs
|
30 |
|
31 | Any URL containing a `~` will be interpreted as a module request. Anything after the `~` will be considered the request path.
|
32 |
|
33 | ```javascript
|
34 | const url = "~path/to/module.js";
|
35 | const request = loaderUtils.urlToRequest(url); // "path/to/module.js"
|
36 | ```
|
37 |
|
38 | #### Root-relative URLs
|
39 |
|
40 | URLs that are root-relative (start with `/`) can be resolved relative to some arbitrary path by using the `root` parameter:
|
41 |
|
42 | ```javascript
|
43 | const url = "/path/to/module.js";
|
44 | const root = "./root";
|
45 | const request = loaderUtils.urlToRequest(url, root); // "./root/path/to/module.js"
|
46 | ```
|
47 |
|
48 | To convert a root-relative URL into a module URL, specify a `root` value that starts with `~`:
|
49 |
|
50 | ```javascript
|
51 | const url = "/path/to/module.js";
|
52 | const root = "~";
|
53 | const request = loaderUtils.urlToRequest(url, root); // "path/to/module.js"
|
54 | ```
|
55 |
|
56 | ### `interpolateName`
|
57 |
|
58 | Interpolates a filename template using multiple placeholders and/or a regular expression.
|
59 | The template and regular expression are set as query params called `name` and `regExp` on the current loader's context.
|
60 |
|
61 | ```javascript
|
62 | const interpolatedName = loaderUtils.interpolateName(
|
63 | loaderContext,
|
64 | name,
|
65 | options
|
66 | );
|
67 | ```
|
68 |
|
69 | The following tokens are replaced in the `name` parameter:
|
70 |
|
71 | - `[ext]` the extension of the resource
|
72 | - `[name]` the basename of the resource
|
73 | - `[path]` the path of the resource relative to the `context` query parameter or option.
|
74 | - `[folder]` the folder the resource is in
|
75 | - `[query]` the queryof the resource, i.e. `?foo=bar`
|
76 | - `[contenthash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the `xxhash64` hash)
|
77 | - `[<hashType>:contenthash:<digestType>:<length>]` optionally one can configure
|
78 | - other `hashType`s, i. e. `xxhash64`, `sha1`, `md4` (wasm version), `native-md4` (`crypto` module version), `md5`, `sha256`, `sha512`
|
79 | - other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
|
80 | - and `length` the length in chars
|
81 | - `[hash]` the hash of `options.content` (Buffer) (by default it's the hex digest of the `xxhash64` hash)
|
82 | - `[<hashType>:hash:<digestType>:<length>]` optionally one can configure
|
83 | - other `hashType`s, i. e. `xxhash64`, `sha1`, `md4` (wasm version), `native-md4` (`crypto` module version), `md5`, `sha256`, `sha512`
|
84 | - other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
|
85 | - and `length` the length in chars
|
86 | - `[N]` the N-th match obtained from matching the current file name against `options.regExp`
|
87 |
|
88 | In loader context `[hash]` and `[contenthash]` are the same, but we recommend using `[contenthash]` for avoid misleading.
|
89 |
|
90 | Examples
|
91 |
|
92 | ```javascript
|
93 | // loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
|
94 | loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext]", { content: ... });
|
95 | // => js/9473fdd0d880a43c21b7778d34872157.script.js
|
96 |
|
97 | // loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
|
98 | // loaderContext.resourceQuery = "?foo=bar"
|
99 | loaderUtils.interpolateName(loaderContext, "js/[hash].script.[ext][query]", { content: ... });
|
100 | // => js/9473fdd0d880a43c21b7778d34872157.script.js?foo=bar
|
101 |
|
102 | // loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
|
103 | loaderUtils.interpolateName(loaderContext, "js/[contenthash].script.[ext]", { content: ... });
|
104 | // => js/9473fdd0d880a43c21b7778d34872157.script.js
|
105 |
|
106 | // loaderContext.resourcePath = "/absolute/path/to/app/page.html"
|
107 | loaderUtils.interpolateName(loaderContext, "html-[hash:6].html", { content: ... });
|
108 | // => html-9473fd.html
|
109 |
|
110 | // loaderContext.resourcePath = "/absolute/path/to/app/flash.txt"
|
111 | loaderUtils.interpolateName(loaderContext, "[hash]", { content: ... });
|
112 | // => c31e9820c001c9c4a86bce33ce43b679
|
113 |
|
114 | // loaderContext.resourcePath = "/absolute/path/to/app/img/image.png"
|
115 | loaderUtils.interpolateName(loaderContext, "[sha512:hash:base64:7].[ext]", { content: ... });
|
116 | // => 2BKDTjl.png
|
117 | // use sha512 hash instead of xxhash64 and with only 7 chars of base64
|
118 |
|
119 | // loaderContext.resourcePath = "/absolute/path/to/app/img/myself.png"
|
120 | // loaderContext.query.name =
|
121 | loaderUtils.interpolateName(loaderContext, "picture.png");
|
122 | // => picture.png
|
123 |
|
124 | // loaderContext.resourcePath = "/absolute/path/to/app/dir/file.png"
|
125 | loaderUtils.interpolateName(loaderContext, "[path][name].[ext]?[hash]", { content: ... });
|
126 | // => /app/dir/file.png?9473fdd0d880a43c21b7778d34872157
|
127 |
|
128 | // loaderContext.resourcePath = "/absolute/path/to/app/js/page-home.js"
|
129 | loaderUtils.interpolateName(loaderContext, "script-[1].[ext]", { regExp: "page-(.*)\\.js", content: ... });
|
130 | // => script-home.js
|
131 |
|
132 | // loaderContext.resourcePath = "/absolute/path/to/app/js/javascript.js"
|
133 | // loaderContext.resourceQuery = "?foo=bar"
|
134 | loaderUtils.interpolateName(
|
135 | loaderContext,
|
136 | (resourcePath, resourceQuery) => {
|
137 | // resourcePath - `/app/js/javascript.js`
|
138 | // resourceQuery - `?foo=bar`
|
139 |
|
140 | return "js/[hash].script.[ext]";
|
141 | },
|
142 | { content: ... }
|
143 | );
|
144 | // => js/9473fdd0d880a43c21b7778d34872157.script.js
|
145 | ```
|
146 |
|
147 | ### `getHashDigest`
|
148 |
|
149 | ```javascript
|
150 | const digestString = loaderUtils.getHashDigest(
|
151 | buffer,
|
152 | hashType,
|
153 | digestType,
|
154 | maxLength
|
155 | );
|
156 | ```
|
157 |
|
158 | - `buffer` the content that should be hashed
|
159 | - `hashType` one of `xxhash64`, `sha1`, `md4`, `md5`, `sha256`, `sha512` or any other node.js supported hash type
|
160 | - `digestType` one of `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
|
161 | - `maxLength` the maximum length in chars
|
162 |
|
163 | ## License
|
164 |
|
165 | MIT (http://www.opensource.org/licenses/mit-license.php)
|