UNPKG

7.94 kBMarkdownView Raw
1[![npm][npm]][npm-url]
2[![node][node]][node-url]
3[![deps][deps]][deps-url]
4[![tests][tests]][tests-url]
5[![coverage][cover]][cover-url]
6[![chat][chat]][chat-url]
7
8<div align="center">
9 <a href="https://github.com/webpack/webpack">
10 <img width="200" height="200"
11 src="https://webpack.js.org/assets/icon-square-big.svg">
12 </a>
13 <h1>File Loader</h1>
14 <p>Instructs webpack to emit the required object as file and to return its public URL</p>
15</div>
16
17<h2 align="center">Install</h2>
18
19```bash
20npm install --save-dev file-loader
21```
22
23<h2 align="center"><a href="https://webpack.js.org/concepts/loaders">Usage</a></h2>
24
25By default the filename of the resulting file is the MD5 hash of the file's contents with the original extension of the required resource.
26
27```js
28import img from './file.png'
29```
30
31**webpack.config.js**
32```js
33module.exports = {
34 module: {
35 rules: [
36 {
37 test: /\.(png|jpg|gif)$/,
38 use: [
39 {
40 loader: 'file-loader',
41 options: {}
42 }
43 ]
44 }
45 ]
46 }
47}
48```
49
50Emits `file.png` as file in the output directory and returns the public URL
51
52```
53"/public/path/0dcbbaa7013869e351f.png"
54```
55
56<h2 align="center">Options</h2>
57
58|Name|Type|Default|Description|
59|:--:|:--:|:-----:|:----------|
60|**`name`**|`{String\|Function}`|`[hash].[ext]`|Configure a custom filename template for your file|
61|**`regExp`**|`{RegExp}`|`'undefined'`|Let you extract some parts of the file path to reuse them in the `name` property|
62|**`context`**|`{String}`|`this.options.context`|Configure a custom file context, defaults to `webpack.config.js` [context](https://webpack.js.org/configuration/entry-context/#context)|
63|**`publicPath`**|`{String\|Function}`|[`__webpack_public_path__ `](https://webpack.js.org/api/module-variables/#__webpack_public_path__-webpack-specific-)|Configure a custom `public` path for your file|
64|**`outputPath`**|`{String\|Function}`|`'undefined'`|Configure a custom `output` path for your file|
65|**`useRelativePath`**|`{Boolean}`|`false`|Should be `true` if you wish to generate a `context` relative URL for each file|
66|**`emitFile`**|`{Boolean}`|`true`|By default a file is emitted, however this can be disabled if required (e.g. for server side packages)|
67
68### `name`
69
70You can configure a custom filename template for your file using the query parameter `name`. For instance, to copy a file from your `context` directory into the output directory retaining the full directory structure, you might use
71
72#### `{String}`
73
74**webpack.config.js**
75```js
76{
77 loader: 'file-loader',
78 options: {
79 name: '[path][name].[ext]'
80 }
81}
82```
83
84#### `{Function}`
85
86**webpack.config.js**
87```js
88{
89 loader: 'file-loader',
90 options: {
91 name (file) {
92 if (env === 'development') {
93 return '[path][name].[ext]'
94 }
95
96 return '[hash].[ext]'
97 }
98 }
99}
100```
101
102### `regExp`
103
104Defines a `regExp` to match some parts of the file path. These capture groups can be reused in the `name` property using `[N]` placeholder. Note that `[0]` will be replaced by the entire tested string, whereas `[1]` will contain the first capturing parenthesis of your regex and so on...
105
106```js
107import img from './customer01/file.png'
108```
109
110**webpack.config.js**
111```js
112{
113 loader: 'file-loader',
114 options: {
115 regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/,
116 name: '[1]-[name].[ext]'
117 }
118}
119```
120
121```
122customer01-file.png
123```
124
125#### `placeholders`
126
127|Name|Type|Default|Description|
128|:--:|:--:|:-----:|:----------|
129|**`[ext]`**|`{String}`|`file.extname`|The extension of the resource|
130|**`[name]`**|`{String}`|`file.basename`|The basename of the resource|
131|**`[path]`**|`{String}`|`file.dirname`|The path of the resource relative to the `context`|
132|**`[hash]`**|`{String}`|`md5`|The hash of the content, hashes below for more info|
133|**`[N]`**|`{String}`|``|The `n-th` match obtained from matching the current file name against the `regExp`|
134
135#### `hashes`
136
137`[<hashType>:hash:<digestType>:<length>]` optionally you can configure
138
139|Name|Type|Default|Description|
140|:--:|:--:|:-----:|:----------|
141|**`hashType`**|`{String}`|`md5`|`sha1`, `md5`, `sha256`, `sha512`|
142|**`digestType`**|`{String}`|`hex`|`hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`|
143|**`length`**|`{Number}`|`9999`|The length in chars|
144
145By default, the path and name you specify will output the file in that same directory and will also use that same URL path to access the file.
146
147### `context`
148
149**webpack.config.js**
150```js
151{
152 loader: 'file-loader',
153 options: {
154 name: '[path][name].[ext]',
155 context: ''
156 }
157}
158```
159
160You can specify custom `output` and `public` paths by using `outputPath`, `publicPath` and `useRelativePath`
161
162### `publicPath`
163
164**webpack.config.js**
165```js
166{
167 loader: 'file-loader',
168 options: {
169 name: '[path][name].[ext]',
170 publicPath: 'assets/'
171 }
172}
173```
174
175### `outputPath`
176
177**webpack.config.js**
178```js
179{
180 loader: 'file-loader',
181 options: {
182 name: '[path][name].[ext]',
183 outputPath: 'images/'
184 }
185}
186```
187
188### `useRelativePath`
189
190`useRelativePath` should be `true` if you wish to generate a relative URL to the for each file context.
191
192```js
193{
194 loader: 'file-loader',
195 options: {
196 useRelativePath: process.env.NODE_ENV === "production"
197 }
198}
199```
200
201### `emitFile`
202
203By default a file is emitted, however this can be disabled if required (e.g. for server side packages).
204
205```js
206import img from './file.png'
207```
208
209```js
210{
211 loader: 'file-loader',
212 options: {
213 emitFile: false
214 }
215}
216```
217
218> ⚠️ Returns the public URL but does **not** emit a file
219
220```
221`${publicPath}/0dcbbaa701328e351f.png`
222```
223
224<h2 align="center">Examples</h2>
225
226
227```js
228import png from 'image.png'
229```
230
231**webpack.config.js**
232```js
233{
234 loader: 'file-loader',
235 options: {
236 name: 'dirname/[hash].[ext]'
237 }
238}
239```
240
241```
242dirname/0dcbbaa701328ae351f.png
243```
244
245**webpack.config.js**
246```js
247{
248 loader: 'file-loader',
249 options: {
250 name: '[sha512:hash:base64:7].[ext]'
251 }
252}
253```
254
255```
256gdyb21L.png
257```
258
259```js
260import png from 'path/to/file.png'
261```
262
263**webpack.config.js**
264```js
265{
266 loader: 'file-loader',
267 options: {
268 name: '[path][name].[ext]?[hash]'
269 }
270}
271```
272
273```
274path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
275```
276
277<h2 align="center">Maintainers</h2>
278
279<table>
280 <tbody>
281 <tr>
282 <td align="center">
283 <a href="https://github.com/bebraw">
284 <img width="150" height="150" src="https://github.com/bebraw.png?v=3&s=150">
285 </br>
286 Juho Vepsäläinen
287 </a>
288 </td>
289 <td align="center">
290 <a href="https://github.com/d3viant0ne">
291 <img width="150" height="150" src="https://github.com/d3viant0ne.png?v=3&s=150">
292 </br>
293 Joshua Wiens
294 </a>
295 </td>
296 <td align="center">
297 <a href="https://github.com/michael-ciniawsky">
298 <img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
299 </br>
300 Michael Ciniawsky
301 </a>
302 </td>
303 <td align="center">
304 <a href="https://github.com/evilebottnawi">
305 <img width="150" height="150" src="https://github.com/evilebottnawi.png?v=3&s=150">
306 </br>
307 Alexander Krasnoyarov
308 </a>
309 </td>
310 </tr>
311 <tbody>
312</table>
313
314
315[npm]: https://img.shields.io/npm/v/file-loader.svg
316[npm-url]: https://npmjs.com/package/file-loader
317
318[node]: https://img.shields.io/node/v/file-loader.svg
319[node-url]: https://nodejs.org
320
321[deps]: https://david-dm.org/webpack-contrib/file-loader.svg
322[deps-url]: https://david-dm.org/webpack-contrib/file-loader
323
324[tests]: http://img.shields.io/travis/webpack-contrib/file-loader.svg
325[tests-url]: https://travis-ci.org/webpack-contrib/file-loader
326
327[cover]: https://img.shields.io/codecov/c/github/webpack-contrib/file-loader.svg
328[cover-url]: https://codecov.io/gh/webpack-contrib/file-loader
329
330[chat]: https://badges.gitter.im/webpack/webpack.svg
331[chat-url]: https://gitter.im/webpack/webpack