[![npm][npm]][npm-url] [![node][node]][node-url] [![deps][deps]][deps-url] [![tests][tests]][tests-url] [![chat][chat]][chat-url]
A file loader module for webpack
This module requires a minimum of Node v6.9.0 and works with Webpack v3 and Webpack v4.
To begin, you'll need to install file-loader
:
$ npm install file-loader --save-dev
Import (or require
) the target file(s) in one of the bundle's files:
// bundle file import img from './file.png'
Then add the loader to your webpack
config. For example:
// webpack.config.js module.exports = { module: { rules: [ { test: /\.(png|jpg|gif)$/, use: [ { loader: 'file-loader', 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.
context
Type: String
Default: context
Specifies a custom file context.
// 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.
// bundle file import img from './file.png'
// 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 the output directory retaining the full directory structure, you might use:
// webpack.config.js { loader: 'file-loader', options: { name: '[path][name].[ext]' } }
Or using a Function
:
// webpack.config.js ... { loader: 'file-loader', options: { name (file) { if (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.
outputPath
Type: String|Function
Default: undefined
Specify a filesystem path where target the file(s) will be placed.
// webpack.config.js ... { loader: 'file-loader', options: { name: '[path][name].[ext]', outputPath: 'images/' } } ...
publicPath
Type: String|Function
Default: __webpack_public_path__
Specifies a custom public path for the target file(s).
// webpack.config.js ... { loader: 'file-loader', options: { name: '[path][name].[ext]', publicPath: 'assets/' } } ...
regExp
Type: RegExp
Default: undefined
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.
import img from './customer01/file.png'
webpack.config.js
{ 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...
useRelativePath
Type: Boolean
Default: false
Specifies whether or not to generate a relative URI for each target file context.
// webpack.config.js { loader: 'file-loader', options: { useRelativePath: process.env.NODE_ENV === "production" } }
[ext]
Type: String
Default: file.extname
The file extension of the target file/resource.
[hash]
Type: String
Default: 'md5'
Specifies the hash method to use for hashing the file content. See Hashes.
[N]
Type: String
Default: undefined
The n-th match obtained from matching the current file name against the regExp
[name]
Type: String
Default: file.basename
The basename of the file/resource.
[path]
Type: String
Default: file.dirname
The path of the resource relative to the webpack/config context.
Custom hashes can be used by specifying a hash with the following format: [<hashType>:hash:<digestType>:<length>]
.
digestType
Type: String
Default: 'hex'
The digest that the hash function should use. Valid values include: base26, base32, base36, base49, base52, base58, base62, base64, and hex.
hashType
Type: String
Default: 'md5'
The type of hash that the has function should use. Valid values include: md5, sha1, sha256, and sha512.
length
Type: Number
Default: 9999
Users may also specify a length for the computed hash.
The following examples show how one might use file-loader
and what the result would be.
// bundle file import png from 'image.png'
// webpack.config.js { loader: 'file-loader', options: { name: 'dirname/[hash].[ext]' } }
# result dirname/0dcbbaa701328ae351f.png
// webpack.config.js { loader: 'file-loader', options: { name: '[sha512:hash:base64:7].[ext]' } }
# result gdyb21L.png
// bundle file import png from 'path/to/file.png'
// webpack.config.js { loader: 'file-loader', options: { name: '[path][name].[ext]?[hash]' } }
# result path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
Please take a moment to read our contributing guidelines if you haven't yet done so.
© JS Foundation and other contributors
Licensed under the Creative Commons Attribution License 4.0.
https://webpack.js.org/loaders/file-loader