file-loader

6.2.0 verified Sat Apr 25 auth: no javascript maintenance

Resolves import/require on a file into a URL and emits the file into the output directory. Stable version 6.2.0 (last release Oct 2020, maintenance mode) with webpack 4/5 support. Key differentiator from alternatives (e.g., url-loader, webpack asset modules) is explicit file emission with custom naming, output path, and public path configuration. Supports hashing, ES modules, and sourceFilename.

Common errors

error Module parse failed: Unexpected token (1:0). You may need an appropriate loader to handle this file type. ↓

cause Missing or misconfigured file-loader rule for the file type.

fix

Add a rule for the file extension, e.g., { test: /\.png$/, loader: 'file-loader' }

error Error: Cannot find module 'file-loader' ↓

cause file-loader not installed.

fix

Run npm install file-loader --save-dev

error TypeError: Cannot read property 'context' of undefined ↓

cause Using outputPath as function without webpack 5 fallback.

fix

Use outputPath string or ensure webpack version compatibility

error Unhandled rejection in promise: Error: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Misconfigured loader options, e.g., misspelled option name.

fix

Check options names (name, outputPath, publicPath, etc.) against documentation

Warnings

breaking Minimum node version increased to 10.13.0 in v5.0.0 ↓

fix Upgrade to Node >=10.13.0 or stay on v4.x

breaking esModule option defaults to true in v5.0.0, outputting ES modules instead of CommonJS ↓

fix Set esModule: false in options if CommonJS required

deprecated esModules option renamed to esModule in v5.0.0 ↓

fix Use esModule instead of esModules

breaking Default hash algorithm changed to md4 in v6.0.0. Older webpack configs relying on md5 may break consistency. ↓

fix Explicitly set hashFunction option to 'md5' if md5 needed

gotcha When using outputPath with a function, the resourcePath is absolute. Relative path must be computed manually. ↓

fix Use path.relative(context, resourcePath) to get relative path

Install

npm install file-loader

yarn add file-loader

pnpm add file-loader

Imports

default
wrong
```
import { img } from './file.png';
```
correct
```
import img from './file.png';
```
file-loader returns the default export as the URL string.

require

wrong

const { img } = require('./file.png');

correct

const img = require('./file.png');

CommonJS usage returns the URL via module.exports.

webpack config

wrong

module.exports = { module: { rules: [ { test: /\.png$/, use: 'file-loader' } ] } };

correct

module.exports = { module: { rules: [ { test: /\.png$/, loader: 'file-loader' } ] } };

use property can be a string or array; Objects with loader/options are also valid.

Quickstart

Shows basic webpack config and usage of file-loader with custom naming and output path.

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

// In your source file
import image from './my-image.png';
console.log(image); // Output: /images/my-image.abc123.png