10 KiB
file-loader
The file-loader resolves import/require() on a file into a url and emits the file into the output directory.
Getting Started
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:
file.js
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.
ℹ️ 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
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 emit a file from your context directory into
the output directory retaining the full directory structure, you might use:
String
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
name: '[path][name].[ext]',
},
},
],
},
};
Function
webpack.config.js
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]';
},
},
},
],
},
};
ℹ️ 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 the target file(s) will be placed.
String
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
outputPath: 'images',
},
},
],
},
};
Function
webpack.config.js
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
Type: String|Function
Default: __webpack_public_path__
Specifies a custom public path for the target file(s).
String
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
publicPath: 'assets',
},
},
],
},
};
Function
webpack.config.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
Specifies a custom file context.
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
// bundle file
import img from './file.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
loader: 'file-loader',
options: {
emitFile: false,
},
},
],
},
};
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.
file.js
import img from './customer01/file.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/,
name: '[1]-[name].[ext]',
},
},
],
},
};
ℹ️ 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.
[ext]
Type: String
Default: file.extname
The file extension of the target file/resource.
[name]
Type: String
Default: file.basename
The basename of the file/resource.
[path]
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
A random emoji representation of content.
[emoji:<length>]
Type: String
Default: undefined
Same as above, but with a customizable number of emojis
[hash]
Type: String
Default: md5
Specifies the hash method to use for hashing the file content.
[<hashType>:hash:<digestType>:<length>]
Type: String
The hash of options.content (Buffer) (by default it's the hex digest of the hash).
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: 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.
file.js
import png from './image.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
name: 'dirname/[hash].[ext]',
},
},
],
},
};
Result:
# result
dirname/0dcbbaa701328ae351f.png
file.js
import png from './image.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
name: '[sha512:hash:base64:7].[ext]',
},
},
],
},
};
Result:
# result
gdyb21L.png
file.js
import png from './path/to/file.png';
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/,
loader: 'file-loader',
options: {
name: '[path][name].[ext]?[hash]',
},
},
],
},
};
Result:
# result
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.