Skip to content

Commit

Permalink
docs(README): standardize (webpack-contrib#171)
Browse files Browse the repository at this point in the history
  • Loading branch information
@michael-ciniawsky @joshwiens
michael-ciniawsky authored and joshwiens committed Aug 8, 2017
1 parent c5b205b commit 7e2998c
Showing 1 changed file with 184 additions and 66 deletions.
250 changes: 184 additions & 66 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
Expand All @@ -10,7 +11,7 @@
src="https://webpack.js.org/assets/icon-square-big.svg">
</a>
<h1>File Loader</h1>
<p>Instructs webpack to emit the required object as file and to return its public url.</p>
<p>Instructs webpack to emit the required object as file and to return its public URL</p>
</div>

<h2 align="center">Install</h2>
Expand All @@ -19,90 +20,215 @@
npm install --save-dev file-loader
```

<h2 align="center">Usage</h2>
<h2 align="center"><a href="https://webpack.js.org/concepts/loaders">Usage</a></h2>

By default the filename of the resulting file is the MD5 hash of the file's contents
with the original extension of the required resource.
By default the filename of the resulting file is the MD5 hash of the file's contents with the original extension of the required resource.

``` javascript
var url = require("file-loader!./file.png");
// => emits file.png as file in the output directory and returns the public url
// => returns i. e. "/public-path/0dcbbaa701328a3c262cfd45869e351f.png"
```js
import img from './file.png'
```

By default a file is emitted, however this can be disabled if required (e.g. for server
side packages).
**webpack.config.js**
```js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
use: [
{
loader: 'file-loader'
options: {}
}
]
}
]
}
}
```

Emits `file.png` as file in the output directory and returns the public URL

```
"/public/path/0dcbbaa7013869e351f.png"
```

<h2 align="center">Options</h2>

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`name`**|`{String}`|`[hash].[ext]`|Configure a custom filename template for your file|
|**`context`**|`{String}`|`this.options.context`|Configure a custom file context, defaults to `webpack.config.js` [context](https://webpack.js.org/configuration/entry-context/#context)|
|**`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 files|
|**`outputPath`**|`{String\|Function}`|`'undefined'`|Configure a custom `output` path for your files|
|**`useRelativePath`**|`{Boolean}`|`false`|Should be `true` if you wish to generate a `context` relative URL for each file|
|**`emitFile`**|`{Boolean}`|`true`|By default a file is emitted, however this can be disabled if required (e.g. for server side packages)|

``` javascript
var url = require("file-loader?emitFile=false!./file.png");
// => returns the public url but does NOT emit a file
// => returns i. e. "/public-path/0dcbbaa701328a3c262cfd45869e351f.png"
### `name`

You 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

**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[path][name].[ext]'
}
}
```

#### Filename templates
#### `placholders`

You 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 `?name=[path][name].[ext]`.
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`[ext]`**|`{String}`|`file.extname`|The extension of the resource|
|**`[name]`**|`{String}`|`file.basename`|The basename of the resource|
|**`[path]`**|`{String}`|`file.dirname`|The path of the resource relative to the `context`|
|**`[hash]`**|`{String}`|`md5`|The hash of the content, hashes below for more info|
|**`[N]`**|`{Number}`|``|The `n-th` match obtained from matching the current file name against the query param `regExp`|

#### `hashes`

`[<hashType>:hash:<digestType>:<length>]` optionally you can configure

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`hashType`**|`{String}`|`md5`|`sha1`, `md5`, `sha256`, `sha512`|
|**`digestType`**|`{String}`|`base64`|`hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`|
|**`length`**|`{Number}`|`8`|The length in chars|

By 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.

You can specify custom output and public paths by using the `outputPath`, `publicPath` and `useRelativePath` query name parameters:
### `context`

**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[path][name].[ext]',
context: ''
}
}
```

You can specify custom `output` and `public` paths by using `outputPath`, `publicPath` and `useRelativePath`

### `publicPath`

**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[path][name].[ext]',
publicPath: 'assets'
}
}
```

### `outputPath`

**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[path][name].[ext]',
outputPath: 'images'
}
}
```

### `useRelativePath`

`useRelativePath` should be `true` if you wish to generate a relative URL to the for each file context.

```js
{
loader: 'file-loader',
options: {
useRelativePath: process.env.NODE_ENV === "production"
}
}
```
use: "file-loader?name=[name].[ext]&publicPath=assets/foo/&outputPath=app/images/"

### `emitFile`

By default a file is emitted, however this can be disabled if required (e.g. for server side packages).

```js
import img from './file.png'
```

`useRelativePath` should be `true` if you wish to generate relative URL to the each file context
```javascript
```js
{
loader: 'file-loader',
query: {
useRelativePath: process.env.NODE_ENV === "production"
}
loader: 'file-loader'
options: {
emitFile: false
}
}
```

#### Filename template placeholders
> ⚠️ Returns the public URL but does **not** emit a file
* `[ext]` the extension of the resource
* `[name]` the basename of the resource
* `[path]` the path of the resource relative to the `context` query parameter or option.
* `[hash]` the hash of the content, `hex`-encoded `md5` by default
* `[<hashType>:hash:<digestType>:<length>]` optionally you can configure
* other `hashType`s, i. e. `sha1`, `md5`, `sha256`, `sha512`
* other `digestType`s, i. e. `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
* and `length` the length in chars
* `[N]` the N-th match obtained from matching the current file name against the query param `regExp`
```
`${publicPath}/0dcbbaa701328e351f.png`
```

#### Examples
<h2 align="center">Examples</h2>

``` javascript
require("file-loader?name=js/[hash].script.[ext]!./javascript.js");
// => js/0dcbbaa701328a3c262cfd45869e351f.script.js

require("file-loader?name=html-[hash:6].html!./page.html");
// => html-109fa8.html
```js
import png from 'image.png'
```

require("file-loader?name=[hash]!./flash.txt");
// => c31e9820c001c9c4a86bce33ce43b679
**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: 'dirname/[hash].[ext]'
}
}
```

require("file-loader?name=[sha512:hash:base64:7].[ext]!./image.png");
// => gdyb21L.png
// use sha512 hash instead of md5 and with only 7 chars of base64
```
dirname/0dcbbaa701328ae351f.png
```

require("file-loader?name=img-[sha512:hash:base64:7].[ext]!./image.jpg");
// => img-VqzT5ZC.jpg
// use custom name, sha512 hash instead of md5 and with only 7 chars of base64
**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[sha512:hash:base64:7].[ext]'
}
}
```

require("file-loader?name=picture.png!./myself.png");
// => picture.png
```
gdyb21L.png
```

require("file-loader?name=[path][name].[ext]?[hash]!./dir/file.png")
// => dir/file.png?e43b20c069c4a01867c31e98cbce33c9
```js
import png from 'path/to/file.png'
```

<h2 align="center">Contributing</h2>
**webpack.config.js**
```js
{
loader: 'file-loader'
options: {
name: '[path][name].[ext]?[hash]'
}
}
```

Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling `npm test`.
```
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
```

<h2 align="center">Maintainers</h2>

Expand All @@ -123,13 +249,6 @@ Don't hesitate to create a pull request. Every contribution is appreciated. In d
Joshua Wiens
</a>
</td>
<td align="center">
<a href="https://github.com/sapegin">
<img width="150" height="150" src="https://github.com/sapegin.png?v=3&s=150">
</br>
Artem Sapegin
</a>
</td>
<td align="center">
<a href="https://github.com/michael-ciniawsky">
<img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
Expand All @@ -149,20 +268,19 @@ Don't hesitate to create a pull request. Every contribution is appreciated. In d
</table>


<h2 align="center">LICENSE</h2>

MIT

[npm]: https://img.shields.io/npm/v/file-loader.svg
[npm-url]: https://npmjs.com/package/file-loader

[node]: https://img.shields.io/node/v/file-loader.svg
[node-url]: https://nodejs.org

[deps]: https://david-dm.org/webpack-contrib/file-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/file-loader

[tests]: http://img.shields.io/travis/webpack-contrib/file-loader.svg
[tests-url]: https://travis-ci.org/webpack-contrib/file-loader

[cover]: https://codecov.io/gh/webpack-contrib/file-loader/branch/master/graph/badge.svg
[cover]: https://img.shields.io/codecov/c/github/webpack-contrib/file-loader.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/file-loader

[chat]: https://badges.gitter.im/webpack/webpack.svg
Expand Down

0 comments on commit 7e2998c

Please sign in to comment.