History

Björn b963b3396c init		5 years ago
..
dist	init	5 years ago
node_modules/schema-utils	init	5 years ago
CHANGELOG.md	init	5 years ago
LICENSE	init	5 years ago
README.md	init	5 years ago
package.json	init	5 years ago

README.md

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 the target 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`