file-loader

Emit files to the output directory and return public URLs (deprecated)

file-loader is deprecated in webpack 5. Use Asset Modules with type: 'asset/resource' instead.

Overview

file-loader resolves imports/requires of files into URLs and emits the files into the output directory. It was commonly used for handling images, fonts, and other file assets.

Migration to Asset Modules

Webpack 5 introduced Asset Modules as a built-in replacement for file-loader, url-loader, and raw-loader.

file-loader (Old - Deprecated)

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif|svg)$/,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[name].[hash].[ext]',
              outputPath: 'images/'
            }
          }
        ]
      }
    ]
  }
};

Installation (Legacy)

Only install if you’re maintaining a legacy webpack 4 project. For webpack 5, use Asset Modules.

npm install -D file-loader

Basic Usage (Legacy)

webpack.config.js

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

Options (Legacy)

name

Configure the output filename:

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

Available placeholders:

• [name] - File basename
• [ext] - File extension
• [path] - File path
• [hash] - Content hash
• [contenthash] - Content hash
• [folder] - Folder name

outputPath

Specify output directory:

{
  loader: 'file-loader',
  options: {
    outputPath: 'images/'
  }
}

publicPath

Customize public path:

{
  loader: 'file-loader',
  options: {
    publicPath: '/assets/'
  }
}

context

Set context for [path]:

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

Common Patterns (Legacy)

Images

{
  test: /\.(png|jpg|jpeg|gif|svg)$/i,
  use: [
    {
      loader: 'file-loader',
      options: {
        name: '[name].[contenthash].[ext]',
        outputPath: 'images/'
      }
    }
  ]
}

Fonts

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

Documents

{
  test: /\.(pdf|doc|docx)$/i,
  use: [
    {
      loader: 'file-loader',
      options: {
        name: '[name].[ext]',
        outputPath: 'documents/'
      }
    }
  ]
}

Complete Migration Guide

Images

Before (file-loader)

{
  test: /\.(png|jpg|gif)$/i,
  loader: 'file-loader',
  options: {
    name: 'images/[name].[hash:8].[ext]'
  }
}

Fonts

Before (file-loader)

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

Custom Output Path

Before (file-loader)

{
  loader: 'file-loader',
  options: {
    outputPath: 'assets/',
    publicPath: '/static/assets/'
  }
}

Asset Modules Advantages

1. Built-in - No external loader required
2. Better Performance - Native webpack implementation
3. Simpler Configuration - Less boilerplate
4. Type Safety - Better TypeScript support
5. Unified API - Consistent with webpack 5 features

Asset Module Types

Webpack 5 provides four asset module types:

asset/resource

Replaces file-loader - emits file and returns URL:

{
  test: /\.png$/,
  type: 'asset/resource'
}

asset/inline

Replaces url-loader - inlines asset as data URI:

{
  test: /\.svg$/,
  type: 'asset/inline'
}

asset/source

Replaces raw-loader - exports source code:

{
  test: /\.txt$/,
  type: 'asset/source'
}

asset

Automatic choice between resource and inline:

{
  test: /\.png$/,
  type: 'asset',
  parser: {
    dataUrlCondition: {
      maxSize: 8 * 1024 // 8kb
    }
  }
}

Complete Migration Example

webpack 4 (file-loader)

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

Key Differences

Feature	file-loader	Asset Modules
Installation	Required	Built-in
Extension	Uses [ext]	Uses [ext] with dot
Configuration	options object	generator object
Performance	Good	Better
Maintenance	Deprecated	Active

In Asset Modules, [ext] includes the leading dot, so use [name][ext] instead of [name].[ext].

Resources

• Asset Modules Guide
• webpack 5 Asset Modules
• Migration from webpack 4
• file-loader GitHub (deprecated)