1 | <div align="center">
|
2 | <a href="https://github.com/webpack/webpack">
|
3 | <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
|
4 | </a>
|
5 | </div>
|
6 |
|
7 | [![npm][npm]][npm-url]
|
8 | [![node][node]][node-url]
|
9 | [![deps][deps]][deps-url]
|
10 | [![tests][tests]][tests-url]
|
11 | [![coverage][cover]][cover-url]
|
12 | [![chat][chat]][chat-url]
|
13 | [![size][size]][size-url]
|
14 |
|
15 | # file-loader
|
16 |
|
17 | The `file-loader` resolves `import`/`require()` on a file into a url and emits the file into the output directory.
|
18 |
|
19 | ## Getting Started
|
20 |
|
21 | To begin, you'll need to install `file-loader`:
|
22 |
|
23 | ```console
|
24 | $ npm install file-loader --save-dev
|
25 | ```
|
26 |
|
27 | Import (or `require`) the target file(s) in one of the bundle's files:
|
28 |
|
29 | **file.js**
|
30 |
|
31 | ```js
|
32 | import img from './file.png';
|
33 | ```
|
34 |
|
35 | Then add the loader to your `webpack` config. For example:
|
36 |
|
37 | **webpack.config.js**
|
38 |
|
39 | ```js
|
40 | module.exports = {
|
41 | module: {
|
42 | rules: [
|
43 | {
|
44 | test: /\.(png|jpg|gif)$/,
|
45 | use: [
|
46 | {
|
47 | loader: 'file-loader',
|
48 | options: {},
|
49 | },
|
50 | ],
|
51 | },
|
52 | ],
|
53 | },
|
54 | };
|
55 | ```
|
56 |
|
57 | And run `webpack` via your preferred method. This will emit `file.png` as a file
|
58 | in the output directory (with the specified naming convention, if options are
|
59 | specified to do so) and returns the public URI of the file.
|
60 |
|
61 | > ℹ️ By default the filename of the resulting file is the hash of the file's contents with the original extension of the required resource.
|
62 |
|
63 | ## Options
|
64 |
|
65 | ### `name`
|
66 |
|
67 | Type: `String|Function`
|
68 | Default: `'[hash].[ext]'`
|
69 |
|
70 | Specifies a custom filename template for the target file(s) using the query
|
71 | parameter `name`. For example, to emit a file from your `context` directory into
|
72 | the output directory retaining the full directory structure, you might use:
|
73 |
|
74 | #### `String`
|
75 |
|
76 | **webpack.config.js**
|
77 |
|
78 | ```js
|
79 | module.exports = {
|
80 | module: {
|
81 | rules: [
|
82 | {
|
83 | test: /\.(png|jpg|gif)$/,
|
84 | loader: 'file-loader',
|
85 | options: {
|
86 | name: '[path][name].[ext]',
|
87 | },
|
88 | },
|
89 | ],
|
90 | },
|
91 | };
|
92 | ```
|
93 |
|
94 | #### `Function`
|
95 |
|
96 | **webpack.config.js**
|
97 |
|
98 | ```js
|
99 | module.exports = {
|
100 | module: {
|
101 | rules: [
|
102 | {
|
103 | test: /\.(png|jpg|gif)$/,
|
104 | loader: 'file-loader',
|
105 | options: {
|
106 | name(file) {
|
107 | if (process.env.NODE_ENV === 'development') {
|
108 | return '[path][name].[ext]';
|
109 | }
|
110 |
|
111 | return '[hash].[ext]';
|
112 | },
|
113 | },
|
114 | },
|
115 | ],
|
116 | },
|
117 | };
|
118 | ```
|
119 |
|
120 | > ℹ️ By default the path and name you specify will output the file in that same directory, and will also use the same URI path to access the file.
|
121 |
|
122 | ### `outputPath`
|
123 |
|
124 | Type: `String|Function`
|
125 | Default: `undefined`
|
126 |
|
127 | Specify a filesystem path where the target file(s) will be placed.
|
128 |
|
129 | #### `String`
|
130 |
|
131 | **webpack.config.js**
|
132 |
|
133 | ```js
|
134 | module.exports = {
|
135 | module: {
|
136 | rules: [
|
137 | {
|
138 | test: /\.(png|jpg|gif)$/,
|
139 | loader: 'file-loader',
|
140 | options: {
|
141 | outputPath: 'images',
|
142 | },
|
143 | },
|
144 | ],
|
145 | },
|
146 | };
|
147 | ```
|
148 |
|
149 | #### `Function`
|
150 |
|
151 | **webpack.config.js**
|
152 |
|
153 | ```js
|
154 | module.exports = {
|
155 | module: {
|
156 | rules: [
|
157 | {
|
158 | test: /\.(png|jpg|gif)$/,
|
159 | loader: 'file-loader',
|
160 | options: {
|
161 | outputPath: (url, resourcePath, context) => {
|
162 | // `resourcePath` is original absolute path to asset
|
163 | // `context` is directory where stored asset (`rootContext`) or `context` option
|
164 |
|
165 | // To get relative path you can use
|
166 | // const relativePath = path.relative(context, resourcePath);
|
167 |
|
168 | if (/my-custom-image\.png/.test(resourcePath)) {
|
169 | return `other_output_path/${url}`;
|
170 | }
|
171 |
|
172 | if (/images/.test(context)) {
|
173 | return `image_output_path/${url}`;
|
174 | }
|
175 |
|
176 | return `output_path/${url}`;
|
177 | },
|
178 | },
|
179 | },
|
180 | ],
|
181 | },
|
182 | };
|
183 | ```
|
184 |
|
185 | ### `publicPath`
|
186 |
|
187 | Type: `String|Function`
|
188 | Default: [`__webpack_public_path__`](https://webpack.js.org/api/module-variables/#__webpack_public_path__-webpack-specific-)
|
189 |
|
190 | Specifies a custom public path for the target file(s).
|
191 |
|
192 | #### `String`
|
193 |
|
194 | **webpack.config.js**
|
195 |
|
196 | ```js
|
197 | module.exports = {
|
198 | module: {
|
199 | rules: [
|
200 | {
|
201 | test: /\.(png|jpg|gif)$/,
|
202 | loader: 'file-loader',
|
203 | options: {
|
204 | publicPath: 'assets',
|
205 | },
|
206 | },
|
207 | ],
|
208 | },
|
209 | };
|
210 | ```
|
211 |
|
212 | #### `Function`
|
213 |
|
214 | **webpack.config.js**
|
215 |
|
216 | ```js
|
217 | module.exports = {
|
218 | module: {
|
219 | rules: [
|
220 | {
|
221 | test: /\.(png|jpg|gif)$/,
|
222 | loader: 'file-loader',
|
223 | options: {
|
224 | publicPath: (url, resourcePath, context) => {
|
225 | // `resourcePath` is original absolute path to asset
|
226 | // `context` is directory where stored asset (`rootContext`) or `context` option
|
227 |
|
228 | // To get relative path you can use
|
229 | // const relativePath = path.relative(context, resourcePath);
|
230 |
|
231 | if (/my-custom-image\.png/.test(resourcePath)) {
|
232 | return `other_public_path/${url}`;
|
233 | }
|
234 |
|
235 | if (/images/.test(context)) {
|
236 | return `image_output_path/${url}`;
|
237 | }
|
238 |
|
239 | return `public_path/${url}`;
|
240 | },
|
241 | },
|
242 | },
|
243 | ],
|
244 | },
|
245 | };
|
246 | ```
|
247 |
|
248 | ### `context`
|
249 |
|
250 | Type: `String`
|
251 | Default: [`context`](https://webpack.js.org/configuration/entry-context/#context)
|
252 |
|
253 | Specifies a custom file context.
|
254 |
|
255 | ```js
|
256 | module.exports = {
|
257 | module: {
|
258 | rules: [
|
259 | {
|
260 | test: /\.(png|jpg|gif)$/,
|
261 | loader: 'file-loader',
|
262 | options: {
|
263 | context: 'project',
|
264 | },
|
265 | },
|
266 | ],
|
267 | },
|
268 | };
|
269 | ```
|
270 |
|
271 | ### `emitFile`
|
272 |
|
273 | Type: `Boolean`
|
274 | Default: `true`
|
275 |
|
276 | If true, emits a file (writes a file to the filesystem). If false, the loader
|
277 | will return a public URI but **will not** emit the file. It is often useful to
|
278 | disable this option for server-side packages.
|
279 |
|
280 | **file.js**
|
281 |
|
282 | ```js
|
283 | // bundle file
|
284 | import img from './file.png';
|
285 | ```
|
286 |
|
287 | **webpack.config.js**
|
288 |
|
289 | ```js
|
290 | module.exports = {
|
291 | module: {
|
292 | rules: [
|
293 | {
|
294 | test: /\.css$/,
|
295 | loader: 'file-loader',
|
296 | options: {
|
297 | emitFile: false,
|
298 | },
|
299 | },
|
300 | ],
|
301 | },
|
302 | };
|
303 | ```
|
304 |
|
305 | ### `regExp`
|
306 |
|
307 | Type: `RegExp`
|
308 | Default: `undefined`
|
309 |
|
310 | Specifies a Regular Expression to one or many parts of the target file path.
|
311 | The capture groups can be reused in the `name` property using `[N]`
|
312 | [placeholder](https://github.com/webpack-contrib/file-loader#placeholders).
|
313 |
|
314 | **file.js**
|
315 |
|
316 | ```js
|
317 | import img from './customer01/file.png';
|
318 | ```
|
319 |
|
320 | **webpack.config.js**
|
321 |
|
322 | ```js
|
323 | module.exports = {
|
324 | module: {
|
325 | rules: [
|
326 | {
|
327 | test: /\.(png|jpg|gif)$/,
|
328 | loader: 'file-loader',
|
329 | options: {
|
330 | regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/,
|
331 | name: '[1]-[name].[ext]',
|
332 | },
|
333 | },
|
334 | ],
|
335 | },
|
336 | };
|
337 | ```
|
338 |
|
339 | > ℹ️ If `[0]` is used, it will be replaced by the entire tested string, whereas `[1]` will contain the first capturing parenthesis of your regex and so on...
|
340 |
|
341 | ## Placeholders
|
342 |
|
343 | Full information about placeholders you can find [here](https://github.com/webpack/loader-utils#interpolatename).
|
344 |
|
345 | ### `[ext]`
|
346 |
|
347 | Type: `String`
|
348 | Default: `file.extname`
|
349 |
|
350 | The file extension of the target file/resource.
|
351 |
|
352 | ### `[name]`
|
353 |
|
354 | Type: `String`
|
355 | Default: `file.basename`
|
356 |
|
357 | The basename of the file/resource.
|
358 |
|
359 | ### `[path]`
|
360 |
|
361 | Type: `String`
|
362 | Default: `file.directory`
|
363 |
|
364 | The path of the resource relative to the webpack/config `context`.
|
365 |
|
366 | ### `[folder]`
|
367 |
|
368 | Type: `String`
|
369 | Default: `file.folder`
|
370 |
|
371 | The folder of the resource is in.
|
372 |
|
373 | ### `[emoji]`
|
374 |
|
375 | Type: `String`
|
376 | Default: `undefined`
|
377 |
|
378 | A random emoji representation of `content`.
|
379 |
|
380 | ### `[emoji:<length>]`
|
381 |
|
382 | Type: `String`
|
383 | Default: `undefined`
|
384 |
|
385 | Same as above, but with a customizable number of emojis
|
386 |
|
387 | ### `[hash]`
|
388 |
|
389 | Type: `String`
|
390 | Default: `md5`
|
391 |
|
392 | Specifies the hash method to use for hashing the file content.
|
393 |
|
394 | ### `[<hashType>:hash:<digestType>:<length>]`
|
395 |
|
396 | Type: `String`
|
397 |
|
398 | The hash of options.content (Buffer) (by default it's the hex digest of the hash).
|
399 |
|
400 | #### `digestType`
|
401 |
|
402 | Type: `String`
|
403 | Default: `'hex'`
|
404 |
|
405 | The [digest](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that the
|
406 | hash function should use. Valid values include: base26, base32, base36,
|
407 | base49, base52, base58, base62, base64, and hex.
|
408 |
|
409 | #### `hashType`
|
410 |
|
411 | Type: `String`
|
412 | Default: `'md5'`
|
413 |
|
414 | The type of hash that the has function should use. Valid values include: `md5`,
|
415 | `sha1`, `sha256`, and `sha512`.
|
416 |
|
417 | #### `length`
|
418 |
|
419 | Type: `Number`
|
420 | Default: `undefined`
|
421 |
|
422 | Users may also specify a length for the computed hash.
|
423 |
|
424 | ### `[N]`
|
425 |
|
426 | Type: `String`
|
427 | Default: `undefined`
|
428 |
|
429 | The n-th match obtained from matching the current file name against the `regExp`.
|
430 |
|
431 | ## Examples
|
432 |
|
433 | The following examples show how one might use `file-loader` and what the result would be.
|
434 |
|
435 | **file.js**
|
436 |
|
437 | ```js
|
438 | import png from './image.png';
|
439 | ```
|
440 |
|
441 | **webpack.config.js**
|
442 |
|
443 | ```js
|
444 | module.exports = {
|
445 | module: {
|
446 | rules: [
|
447 | {
|
448 | test: /\.(png|jpg|gif)$/,
|
449 | loader: 'file-loader',
|
450 | options: {
|
451 | name: 'dirname/[hash].[ext]',
|
452 | },
|
453 | },
|
454 | ],
|
455 | },
|
456 | };
|
457 | ```
|
458 |
|
459 | Result:
|
460 |
|
461 | ```bash
|
462 | # result
|
463 | dirname/0dcbbaa701328ae351f.png
|
464 | ```
|
465 |
|
466 | ---
|
467 |
|
468 | **file.js**
|
469 |
|
470 | ```js
|
471 | import png from './image.png';
|
472 | ```
|
473 |
|
474 | **webpack.config.js**
|
475 |
|
476 | ```js
|
477 | module.exports = {
|
478 | module: {
|
479 | rules: [
|
480 | {
|
481 | test: /\.(png|jpg|gif)$/,
|
482 | loader: 'file-loader',
|
483 | options: {
|
484 | name: '[sha512:hash:base64:7].[ext]',
|
485 | },
|
486 | },
|
487 | ],
|
488 | },
|
489 | };
|
490 | ```
|
491 |
|
492 | Result:
|
493 |
|
494 | ```bash
|
495 | # result
|
496 | gdyb21L.png
|
497 | ```
|
498 |
|
499 | ---
|
500 |
|
501 | **file.js**
|
502 |
|
503 | ```js
|
504 | import png from './path/to/file.png';
|
505 | ```
|
506 |
|
507 | **webpack.config.js**
|
508 |
|
509 | ```js
|
510 | module.exports = {
|
511 | module: {
|
512 | rules: [
|
513 | {
|
514 | test: /\.(png|jpg|gif)$/,
|
515 | loader: 'file-loader',
|
516 | options: {
|
517 | name: '[path][name].[ext]?[hash]',
|
518 | },
|
519 | },
|
520 | ],
|
521 | },
|
522 | };
|
523 | ```
|
524 |
|
525 | Result:
|
526 |
|
527 | ```bash
|
528 | # result
|
529 | path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
|
530 | ```
|
531 |
|
532 | ## Contributing
|
533 |
|
534 | Please take a moment to read our contributing guidelines if you haven't yet done so.
|
535 |
|
536 | [CONTRIBUTING](./.github/CONTRIBUTING.md)
|
537 |
|
538 | ## License
|
539 |
|
540 | [MIT](./LICENSE)
|
541 |
|
542 | [npm]: https://img.shields.io/npm/v/file-loader.svg
|
543 | [npm-url]: https://npmjs.com/package/file-loader
|
544 | [node]: https://img.shields.io/node/v/file-loader.svg
|
545 | [node-url]: https://nodejs.org
|
546 | [deps]: https://david-dm.org/webpack-contrib/file-loader.svg
|
547 | [deps-url]: https://david-dm.org/webpack-contrib/file-loader
|
548 | [tests]: https://img.shields.io/circleci/project/github/webpack-contrib/file-loader.svg
|
549 | [tests-url]: https://circleci.com/gh/webpack-contrib/file-loader
|
550 | [cover]: https://codecov.io/gh/webpack-contrib/file-loader/branch/master/graph/badge.svg
|
551 | [cover-url]: https://codecov.io/gh/webpack-contrib/file-loader
|
552 | [chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
|
553 | [chat-url]: https://gitter.im/webpack/webpack
|
554 | [size]: https://packagephobia.now.sh/badge?p=file-loader
|
555 | [size-url]: https://packagephobia.now.sh/result?p=file-loader
|