From 269d3fb92cba30d5e141fb62c6b1274524c4fb69 Mon Sep 17 00:00:00 2001 From: Evilebot Tnawi Date: Thu, 20 Dec 2018 17:54:41 +0300 Subject: [PATCH] docs: improve README (#307) --- README.md | 554 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 333 insertions(+), 221 deletions(-) diff --git a/README.md b/README.md index 1549b26..df3d417 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,13 @@ [![node][node]][node-url] [![deps][deps]][deps-url] [![tests][tests]][tests-url] +[![coverage][cover]][cover-url] [![chat][chat]][chat-url] +[![size][size]][size-url] # file-loader -A file loader module for webpack +The `file-loader` resolves `import`/`require()` on a file into a url and emits the file into the output directory. ## Getting Started @@ -24,15 +26,17 @@ $ npm install file-loader --save-dev Import (or `require`) the target file(s) in one of the bundle's files: +**file.js** + ```js -// bundle file -import img from './file.png' +import img from './file.png'; ``` Then add the loader to your `webpack` config. For example: +**webpack.config.js** + ```js -// webpack.config.js module.exports = { module: { rules: [ @@ -41,113 +45,79 @@ module.exports = { use: [ { loader: 'file-loader', - options: {} - } - ] - } - ] - } -} + options: {}, + }, + ], + }, + ], + }, +}; ``` And run `webpack` via your preferred method. This will emit `file.png` as a file in the output directory (with the specified naming convention, if options are specified to do so) and returns the public URI of the file. -_Note: 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 hash of the file's contents with the original extension of the required resource. ## Options -### `context` - -Type: `String` -Default: [`context`](https://webpack.js.org/configuration/entry-context/#context) - -Specifies a custom file context. - -```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]', - context: '' - } -} -... -``` - -### `emitFile` - -Type: `Boolean` -Default: `true` - -If true, emits a file (writes a file to the filesystem). If false, the loader -will return a public URI but _will not_ emit the file. It is often useful to -disable this option for server-side packages. - -```js -// bundle file -import img from './file.png' -``` - -```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - emitFile: false - } -} -... -``` - ### `name` Type: `String|Function` Default: `'[hash].[ext]'` Specifies a custom filename template for the target file(s) using the query -parameter `name`. For example, to copy a file from your `context` directory into +parameter `name`. For example, to emit a file from your `context` directory into the output directory retaining the full directory structure, you might use: #### `String` +**webpack.config.js** + ```js -// webpack.config.js -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]' - } -} +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + name: '[path][name].[ext]', + }, + }, + ], + }, +}; ``` #### `Function` +**webpack.config.js** + ```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name (file) { - if (env === 'development') { - return '[path][name].[ext]' - } - - return '[hash].[ext]' - } - } -} -... +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + name(file) { + if (process.env.NODE_ENV === 'development') { + return '[path][name].[ext]'; + } + + return '[hash].[ext]'; + }, + }, + }, + ], + }, +}; ``` -_Note: 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._ +> ℹ️ 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. ### `outputPath` @@ -158,48 +128,58 @@ Specify a filesystem path where the target file(s) will be placed. #### `String` +**webpack.config.js** + ```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]', - outputPath: 'images/' - } -} -... +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + outputPath: 'images', + }, + }, + ], + }, +}; ``` #### `Function` +**webpack.config.js** + ```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]', - outputPath: (url, resourcePath, context) => { - // `resourcePath` is original absolute path to asset - // `context` is directory where stored asset (`rootContext`) or `context` option - - // To get relative path you can use - // const relativePath = path.relative(context, resourcePath); - - if (/my-custom-image\.png/.test(resourcePath)) { - return `other_output_path/${url}` - } - - if (/images/.test(context)) { - return `image_output_path/${url}`; - } - - return `output_path/${url}`; - }, - } -} -... +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + outputPath: (url, resourcePath, context) => { + // `resourcePath` is original absolute path to asset + // `context` is directory where stored asset (`rootContext`) or `context` option + + // To get relative path you can use + // const relativePath = path.relative(context, resourcePath); + + if (/my-custom-image\.png/.test(resourcePath)) { + return `other_output_path/${url}`; + } + + if (/images/.test(context)) { + return `image_output_path/${url}`; + } + + return `output_path/${url}`; + }, + }, + }, + ], + }, +}; ``` ### `publicPath` @@ -211,48 +191,115 @@ Specifies a custom public path for the target file(s). #### `String` +**webpack.config.js** + ```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]', - publicPath: 'assets/' - } -} -... +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + publicPath: 'assets', + }, + }, + ], + }, +}; ``` #### `Function` +**webpack.config.js** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + publicPath: (url, resourcePath, context) => { + // `resourcePath` is original absolute path to asset + // `context` is directory where stored asset (`rootContext`) or `context` option + + // To get relative path you can use + // const relativePath = path.relative(context, resourcePath); + + if (/my-custom-image\.png/.test(resourcePath)) { + return `other_public_path/${url}`; + } + + if (/images/.test(context)) { + return `image_output_path/${url}`; + } + + return `public_path/${url}`; + }, + }, + }, + ], + }, +}; +``` + +### `context` + +Type: `String` +Default: [`context`](https://webpack.js.org/configuration/entry-context/#context) + +Specifies a custom file context. + ```js -// webpack.config.js -... -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]', - publicPath: (url, resourcePath, context) => { - // `resourcePath` is original absolute path to asset - // `context` is directory where stored asset (`rootContext`) or `context` option - - // To get relative path you can use - // const relativePath = path.relative(context, resourcePath); - - if (/my-custom-image\.png/.test(resourcePath)) { - return `other_public_path/${url}` - } - - if (/images/.test(context)) { - return `image_output_path/${url}`; - } - - return `public_path/${url}`; - } - } -} -... +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + context: 'project', + }, + }, + ], + }, +}; +``` + +### `emitFile` + +Type: `Boolean` +Default: `true` + +If true, emits a file (writes a file to the filesystem). If false, the loader +will return a public URI but **will not** emit the file. It is often useful to +disable this option for server-side packages. + +**file.js** + +```js +// bundle file +import img from './file.png'; +``` + +**webpack.config.js** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.css$/, + loader: 'file-loader', + options: { + emitFile: false, + }, + }, + ], + }, +}; ``` ### `regExp` @@ -264,27 +311,37 @@ Specifies a Regular Expression to one or many parts of the target file path. The capture groups can be reused in the `name` property using `[N]` [placeholder](https://github.com/webpack-contrib/file-loader#placeholders). +**file.js** + ```js -import img from './customer01/file.png' +import img from './customer01/file.png'; ``` **webpack.config.js** + ```js -{ - loader: 'file-loader', - options: { - regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/, - name: '[1]-[name].[ext]' - } -} +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/, + name: '[1]-[name].[ext]', + }, + }, + ], + }, +}; ``` -_Note: 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..._ +> ℹ️ 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... ## Placeholders +Full information about placeholders you can find [here](https://github.com/webpack/loader-utils#interpolatename). + ### `[ext]` Type: `String` @@ -292,41 +349,55 @@ Default: `file.extname` The file extension of the target file/resource. -### `[hash]` +### `[name]` Type: `String` -Default: `'md5'` +Default: `file.basename` + +The basename of the file/resource. -Specifies the hash method to use for hashing the file content. See -[Hashes](https://github.com/webpack-contrib/file-loader#hashes). +### `[path]` -### `[N]` +Type: `String` +Default: `file.directory` + +The path of the resource relative to the webpack/config `context`. + +### `[folder]` + +Type: `String` +Default: `file.folder` + +The folder of the resource is in. + +### `[emoji]` Type: `String` Default: `undefined` -The n-th match obtained from matching the current file name against the regExp +A random emoji representation of `content`. -### `[name]` +### `[emoji:]` Type: `String` -Default: `file.basename` +Default: `undefined` -The basename of the file/resource. +Same as above, but with a customizable number of emojis -### `[path]` +### `[hash]` Type: `String` -Default: `file.dirname` +Default: `md5` -The path of the resource relative to the webpack/config context. +Specifies the hash method to use for hashing the file content. -## Hashes +### `[:hash::]` -Custom hashes can be used by specifying a hash with the following format: - `[:hash::]`. +Type: `String` -### `digestType` +The hash of options.content (Buffer) (by default it's the hex digest of the hash). + +#### `digestType` Type: `String` Default: `'hex'` @@ -335,41 +406,58 @@ The [digest](https://en.wikipedia.org/wiki/Cryptographic_hash_function) that the hash function should use. Valid values include: base26, base32, base36, base49, base52, base58, base62, base64, and hex. -### `hashType` +#### `hashType` Type: `String` Default: `'md5'` -The type of hash that the has function should use. Valid values include: md5, -sha1, sha256, and sha512. +The type of hash that the has function should use. Valid values include: `md5`, +`sha1`, `sha256`, and `sha512`. -### `length` +#### `length` Type: `Number` -Default: `9999` +Default: `undefined` Users may also specify a length for the computed hash. +### `[N]` + +Type: `String` +Default: `undefined` + +The n-th match obtained from matching the current file name against the `regExp`. + ## Examples -The following examples show how one might use `file-loader` and what the result -would be. +The following examples show how one might use `file-loader` and what the result would be. + +**file.js** ```js -// bundle file -import png from 'image.png' +import png from './image.png'; ``` +**webpack.config.js** + ```js -// webpack.config.js -{ - loader: 'file-loader', - options: { - name: 'dirname/[hash].[ext]' - } -} +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + name: 'dirname/[hash].[ext]', + }, + }, + ], + }, +}; ``` +Result: + ```bash # result dirname/0dcbbaa701328ae351f.png @@ -377,16 +465,32 @@ dirname/0dcbbaa701328ae351f.png --- +**file.js** + ```js -// webpack.config.js -{ - loader: 'file-loader', - options: { - name: '[sha512:hash:base64:7].[ext]' - } -} +import png from './image.png'; ``` +**webpack.config.js** + +```js +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + name: '[sha512:hash:base64:7].[ext]', + }, + }, + ], + }, +}; +``` + +Result: + ```bash # result gdyb21L.png @@ -394,21 +498,32 @@ gdyb21L.png --- +**file.js** + ```js -// bundle file -import png from 'path/to/file.png' +import png from './path/to/file.png'; ``` +**webpack.config.js** + ```js -// webpack.config.js -{ - loader: 'file-loader', - options: { - name: '[path][name].[ext]?[hash]' - } -} +module.exports = { + module: { + rules: [ + { + test: /\.(png|jpg|gif)$/, + loader: 'file-loader', + options: { + name: '[path][name].[ext]?[hash]', + }, + }, + ], + }, +}; ``` +Result: + ```bash # result path/to/file.png?e43b20c069c4a01867c31e98cbce33c9 @@ -426,18 +541,15 @@ Please take a moment to read our contributing guidelines if you haven't yet done [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]: https://img.shields.io/circleci/project/github/webpack-contrib/file-loader.svg +[tests]: https://img.shields.io/circleci/project/github/webpack-contrib/file-loader.svg [tests-url]: https://circleci.com/gh/webpack-contrib/file-loader - [cover]: https://codecov.io/gh/webpack-contrib/file-loader/branch/master/graph/badge.svg [cover-url]: https://codecov.io/gh/webpack-contrib/file-loader - [chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg [chat-url]: https://gitter.im/webpack/webpack +[size]: https://packagephobia.now.sh/badge?p=file-loader +[size-url]: https://packagephobia.now.sh/result?p=file-loader