file-loader

A file loader module for webpack

Requirements

This module requires a minimum of Node v6.9.0 and works with Webpack v3 and Webpack v4.

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:

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

Options

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"
  }
}

Placeholders

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

Hashes

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.

Examples

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

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT