Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import img from './file.png';
✗ import { img } from './file.png';
file-loader returns the default export as the URL string.
require
✓ const img = require('./file.png');
✗ const { img } = require('./file.png');
CommonJS usage returns the URL via module.exports.
webpack config
✓ module.exports = { module: { rules: [ { test: /\.png$/, loader: 'file-loader' } ] } };
✗ module.exports = { module: { rules: [ { test: /\.png$/, use: 'file-loader' } ] } };
use property can be a string or array; Objects with loader/options are also valid.
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
Errors
Common errors & fixes
Module parse failed: Unexpected token (1:0). You may need an appropriate loader to handle this file type.
Missing or misconfigured file-loader rule for the file type.
fixAdd a rule for the file extension, e.g., { test: /\.png$/, loader: 'file-loader' } Error: Cannot find module 'file-loader'
file-loader not installed.
fixRun npm install file-loader --save-dev
TypeError: Cannot read property 'context' of undefined
Using outputPath as function without webpack 5 fallback.
fixUse outputPath string or ensure webpack version compatibility
Unhandled rejection in promise: Error: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.
Misconfigured loader options, e.g., misspelled option name.
fixCheck options names (name, outputPath, publicPath, etc.) against documentation
Audit
Dependencies
webpackrequiredpeer dependency, required to operate as a loader