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.
url-loader
✓ module.exports = { module: { rules: [ { test: /\.(png|jpg)$/i, use: [ { loader: 'url-loader', options: { limit: 8192 } } ] } ] } }
✗ import urlLoader from 'url-loader'
url-loader is a webpack loader, not a JavaScript module. It is configured in webpack.config.js as a loader string. In webpack 5 asset modules may be preferred over url-loader.
default export
✓ module.exports = { module: { rules: [ { test: /\.(png)$/i, use: ['url-loader'] } ] } }
✗ const urlLoader = require('url-loader'); ... use: [ urlLoader ]
The loader is referenced by its package name string, not by requiring the package directly. Direct require works but is unconventional.
esModule option
✓ options: { esModule: true }
✗ options: { esModules: true }
In v3.0.0 the option was renamed from esModules to esModule (breaking change). When esModule: true (default since v3.0.0), output uses ES module syntax.
fallback option
✓ options: { fallback: 'responsive-loader' }
✗ options: { fallbackLoader: 'responsive-loader' }
The fallback option accepts a string name of another loader (default 'file-loader'). It is not called fallbackLoader.
Quickstart: install url-loader, configure webpack rule with 8KB limit, and import images as data URLs or file paths.
// Install
npm install url-loader file-loader --save-dev
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif|svg)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192, // inline files < 8KB as base64
fallback: 'file-loader', // for larger files
esModule: true, // use ES module syntax
},
},
],
},
],
},
};
// In your source code
import logo from './logo.png'; // if < 8KB, logo = base64 data URL; if >= 8KB, logo = file path
// Example usage
const img = document.createElement('img');
img.src = logo;
document.body.appendChild(img);
Errors
Common errors & fixes
Module build failed (from ./node_modules/url-loader/dist/cjs.js): TypeError: Cannot read property 'mime' of undefined
Missing or outdated mime-types dependency (v4.0.0+ requires mime-types, not mime).
fixRun: npm install mime-types@latest. Or reinstall url-loader: npm install url-loader@latest.
Error: resolve 'file-loader' ... ModuleNotFoundError: Module not found: Error: Can't resolve 'file-loader'
file-loader is not installed but is needed as fallback when files exceed limit.
fixInstall file-loader: npm install file-loader --save-dev. Or set fallback option to an installed loader.
ERROR in ./src/logo.png 1:0 Module parse failed: Unexpected character '�' (1:0) ... You may need an appropriate loader to handle this file type.
url-loader is not configured in webpack rules or test pattern does not match .png files.
fixAdd rule with test: /\.(png|jpg|gif)$/i and use 'url-loader' in webpack config.
Configuration error: 'esModules' is not a valid option for url-loader.
Using old option name 'esModules' instead of 'esModule' (renamed in v3.0.0).
fixChange option to 'esModule' (note: singular, no 's').
Cannot find module 'schema-utils'
Missing dependency 'schema-utils' (used for option validation).
fixReinstall url-loader: npm install url-loader@latest. Or manually install: npm install schema-utils.
Audit
Dependencies
webpackrequiredPeer dependency: url-loader operates as a webpack loader, requiring webpack 4 or 5.
file-loaderoptionalPeer dependency: used by default as fallback when file size exceeds the limit.
mime-typesrequiredRuntime dependency: used to determine MIME type for files. Changed from mime to mime-types in v4.0.0 (breaking change).
schema-utilsrequiredRuntime dependency: validates loader options against a JSON schema. Updated in v4.1.1.