url-loader

4.1.1 verified Sat Apr 25 auth: no javascript

url-loader is a webpack loader that transforms files into base64 data URLs when their size is below a configurable limit (default no limit, recommended 8KB or less). Current stable version is 4.1.1 (October 2020), with no new releases since then; it supports webpack 4 and 5. It works like file-loader but inlines small files as base64, reducing HTTP requests. Key differentiators: built-in fallback to file-loader for larger files, customizable MIME type detection via mime-types, encoding options (e.g., base64, hex), and support for ES module output. It is part of the webpack-contrib ecosystem and commonly used with webpack's asset pipeline.

Common errors

error Module build failed (from ./node_modules/url-loader/dist/cjs.js): TypeError: Cannot read property 'mime' of undefined ↓

cause Missing or outdated mime-types dependency (v4.0.0+ requires mime-types, not mime).

fix

Run: npm install mime-types@latest. Or reinstall url-loader: npm install url-loader@latest.

error Error: resolve 'file-loader' ... ModuleNotFoundError: Module not found: Error: Can't resolve 'file-loader' ↓

cause file-loader is not installed but is needed as fallback when files exceed limit.

fix

Install file-loader: npm install file-loader --save-dev. Or set fallback option to an installed loader.

error 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. ↓

cause url-loader is not configured in webpack rules or test pattern does not match .png files.

fix

Add rule with test: /\.(png|jpg|gif)$/i and use 'url-loader' in webpack config.

error Configuration error: 'esModules' is not a valid option for url-loader. ↓

cause Using old option name 'esModules' instead of 'esModule' (renamed in v3.0.0).

fix

Change option to 'esModule' (note: singular, no 's').

error Cannot find module 'schema-utils' ↓

cause Missing dependency 'schema-utils' (used for option validation).

fix

Reinstall url-loader: npm install url-loader@latest. Or manually install: npm install schema-utils.

Warnings

breaking v4.0.0 migrated from 'mime' package to 'mime-types'. Some file types may have different MIME type mapping, potentially breaking inline behavior for rare types. ↓

fix If you rely on specific MIME types, verify the mapping with the mime-types package. You can override with the 'mimetype' option.

breaking v3.0.0 renamed 'esModules' option to 'esModule' and made ES module output default (true). ↓

fix If using 'esModules: false' in v2, change to 'esModule: false' in v3+. If you rely on CommonJS output, set esModule: false.

breaking v3.0.0 dropped support for Node.js < 10.13.0. ↓

fix Upgrade Node.js to 10.13.0 or newer.

gotcha When limit is 0 or false, all files are passed to fallback (file-loader by default). Setting limit to 0 does NOT mean "no limit" but rather "treat all files as larger than limit". ↓

fix To inline all files, either omit limit or set limit to Number.MAX_VALUE or use a very high value. Or use asset modules in webpack 5.

gotcha If file-loader is not installed, url-loader will throw an error when fallback is triggered (file size >= limit). ↓

fix Install file-loader as a peer dependency: npm install file-loader --save-dev. Or specify a different fallback loader.

deprecated webpack 5 introduced asset modules (type: 'asset' / 'asset/inline') that supersede url-loader and file-loader. url-loader still works but is considered legacy. ↓

fix For new projects, use asset modules: { test: /\.png$/, type: 'asset', parser: { dataUrlCondition: { maxSize: 8192 } } }

Install

npm install url-loader

yarn add url-loader

pnpm add url-loader

Imports

url-loader
wrong
```
import urlLoader from 'url-loader'
```
correct
```
module.exports = { module: { rules: [ { test: /\.(png|jpg)$/i, use: [ { loader: 'url-loader', options: { limit: 8192 } } ] } ] } }
```
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
wrong
```
const urlLoader = require('url-loader'); ... use: [ urlLoader ]
```
correct
```
module.exports = { module: { rules: [ { test: /\.(png)$/i, use: ['url-loader'] } ] } }
```
The loader is referenced by its package name string, not by requiring the package directly. Direct require works but is unconventional.
esModule option
wrong
```
options: { esModules: true }
```
correct
```
options: { esModule: 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
wrong
```
options: { fallbackLoader: 'responsive-loader' }
```
correct
```
options: { fallback: 'responsive-loader' }
```
The fallback option accepts a string name of another loader (default 'file-loader'). It is not called fallbackLoader.

Quickstart

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);