file-loader

What is file-loader?

The file-loader npm package is used to process files such as images, fonts, and other binary assets within a webpack build process. It can copy files to the output directory and resolve import/require() on a file into a url.

What are file-loader's main functionalities?

Importing Images

Allows importing image files directly in JavaScript or TypeScript files. The file-loader processes the import and replaces it with the final path to the output file.

import img from './file.png';

Configuring Output Path and Filenames

Configures webpack to output files with a specific naming pattern and to a specific directory. It also allows setting a public path for the files when they are referenced in the browser.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext]',
              outputPath: 'images/',
              publicPath: 'assets/',
            },
          },
        ],
      },
    ],
  },
};

Handling Fonts

Enables the inclusion and processing of font files in various formats. The file-loader will handle these assets and output them to a specified directory.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(woff|woff2|eot|ttf|otf)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[name].[ext]',
              outputPath: 'fonts/',
            },
          },
        ],
      },
    ],
  },
};

Other packages similar to file-loader

url-loader

The url-loader works like the file-loader, but can return a Data URL if the file is smaller than a byte limit. This can reduce the number of HTTP requests for small files.

raw-loader

The raw-loader allows importing files as a string. This is useful for importing things like HTML or SVG directly into your JavaScript code, which is different from file-loader's typical binary asset handling.

copy-webpack-plugin

This plugin allows copying individual files or entire directories to the build directory. It is more flexible than file-loader for simply copying files without processing them through webpack's module system.

README

File Loader

Instructs webpack to emit the required object as file and to return its public URL

Install

npm install --save-dev file-loader

Usage

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.

import img from './file.png'

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/,
        use: [
          {
            loader: 'file-loader',
            options: {}  
          }
        ]
      }
    ]
  }
}

Emits file.png as file in the output directory and returns the public URL

"/public/path/0dcbbaa7013869e351f.png"

Options

Name	Type	Default	Description
name	{String}	[hash].[ext]	Configure a custom filename template for your file
context	{String}	this.options.context	Configure a custom file context, defaults to webpack.config.js context
publicPath	{String|Function}	__webpack_public_path__	Configure a custom public path for your files
outputPath	{String|Function}	'undefined'	Configure a custom output path for your files
useRelativePath	{Boolean}	false	Should be true if you wish to generate a context relative URL for each file
emitFile	{Boolean}	true	By default a file is emitted, however this can be disabled if required (e.g. for server side packages)

name

You can configure a custom filename template for your file using the query parameter name. For instance, 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]'
  }  
}

placeholders

Name	Type	Default	Description
[ext]	{String}	file.extname	The extension of the resource
[name]	{String}	file.basename	The basename of the resource
[path]	{String}	file.dirname	The path of the resource relative to the context
[hash]	{String}	md5	The hash of the content, hashes below for more info
[N]	{Number}	``	The n-th match obtained from matching the current file name against the query param regExp

hashes

[<hashType>:hash:<digestType>:<length>] optionally you can configure

Name	Type	Default	Description
hashType	{String}	md5	sha1, md5, sha256, sha512
digestType	{String}	base64	hex, base26, base32, base36, base49, base52, base58, base62, base64
length	{Number}	8	The length in chars

By default, the path and name you specify will output the file in that same directory and will also use that same URL path to access the file.

context

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    context: ''
  }  
}

You can specify custom output and public paths by using outputPath, publicPath and useRelativePath

publicPath

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    publicPath: 'assets'
  }  
}

outputPath

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]',
    outputPath: 'images'
  }  
}

useRelativePath

useRelativePath should be true if you wish to generate a relative URL to the for each file context.

{
  loader: 'file-loader',
  options: {
    useRelativePath: process.env.NODE_ENV === "production"
  }
}

emitFile

By default a file is emitted, however this can be disabled if required (e.g. for server side packages).

import img from './file.png'

{
  loader: 'file-loader',
  options: {
    emitFile: false
  }  
}

⚠️ Returns the public URL but does not emit a file

`${publicPath}/0dcbbaa701328e351f.png`

Examples

import png from 'image.png'

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: 'dirname/[hash].[ext]'
  }  
}

dirname/0dcbbaa701328ae351f.png

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: '[sha512:hash:base64:7].[ext]'
  }  
}

gdyb21L.png

import png from 'path/to/file.png'

webpack.config.js

{
  loader: 'file-loader',
  options: {
    name: '[path][name].[ext]?[hash]'
  }  
}

path/to/file.png?e43b20c069c4a01867c31e98cbce33c9

Maintainers

Juho Vepsäläinen

Joshua Wiens

Michael Ciniawsky

Alexander Krasnoyarov

Changelog

1.1.1 (2017-09-30)

Bug Fixes

• schema: allow additionalProperties (#207) (cf7c85a)

<a name="1.1.0"></a>