{"id":20651,"library":"url-loader","title":"url-loader","description":"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.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/webpack-contrib/url-loader","tags":["javascript","webpack"],"install":[{"cmd":"npm install url-loader","lang":"bash","label":"npm"},{"cmd":"yarn add url-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add url-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency: url-loader operates as a webpack loader, requiring webpack 4 or 5.","package":"webpack","optional":false},{"reason":"Peer dependency: used by default as fallback when file size exceeds the limit.","package":"file-loader","optional":true},{"reason":"Runtime dependency: used to determine MIME type for files. Changed from mime to mime-types in v4.0.0 (breaking change).","package":"mime-types","optional":false},{"reason":"Runtime dependency: validates loader options against a JSON schema. Updated in v4.1.1.","package":"schema-utils","optional":false}],"imports":[{"note":"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.","wrong":"import urlLoader from 'url-loader'","symbol":"url-loader","correct":"module.exports = { module: { rules: [ { test: /\\.(png|jpg)$/i, use: [ { loader: 'url-loader', options: { limit: 8192 } } ] } ] } }"},{"note":"The loader is referenced by its package name string, not by requiring the package directly. Direct require works but is unconventional.","wrong":"const urlLoader = require('url-loader'); ... use: [ urlLoader ]","symbol":"default export","correct":"module.exports = { module: { rules: [ { test: /\\.(png)$/i, use: ['url-loader'] } ] } }"},{"note":"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.","wrong":"options: { esModules: true }","symbol":"esModule option","correct":"options: { esModule: true }"},{"note":"The fallback option accepts a string name of another loader (default 'file-loader'). It is not called fallbackLoader.","wrong":"options: { fallbackLoader: 'responsive-loader' }","symbol":"fallback option","correct":"options: { fallback: 'responsive-loader' }"}],"quickstart":{"code":"// Install\nnpm install url-loader file-loader --save-dev\n\n// webpack.config.js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.(png|jpg|gif|svg)$/i,\n        use: [\n          {\n            loader: 'url-loader',\n            options: {\n              limit: 8192, // inline files < 8KB as base64\n              fallback: 'file-loader', // for larger files\n              esModule: true, // use ES module syntax\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n\n// In your source code\nimport logo from './logo.png'; // if < 8KB, logo = base64 data URL; if >= 8KB, logo = file path\n\n// Example usage\nconst img = document.createElement('img');\nimg.src = logo;\ndocument.body.appendChild(img);","lang":"javascript","description":"Quickstart: install url-loader, configure webpack rule with 8KB limit, and import images as data URLs or file paths."},"warnings":[{"fix":"If you rely on specific MIME types, verify the mapping with the mime-types package. You can override with the 'mimetype' option.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If using 'esModules: false' in v2, change to 'esModule: false' in v3+. If you rely on CommonJS output, set esModule: false.","message":"v3.0.0 renamed 'esModules' option to 'esModule' and made ES module output default (true).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node.js to 10.13.0 or newer.","message":"v3.0.0 dropped support for Node.js < 10.13.0.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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\".","severity":"gotcha","affected_versions":"all"},{"fix":"Install file-loader as a peer dependency: npm install file-loader --save-dev. Or specify a different fallback loader.","message":"If file-loader is not installed, url-loader will throw an error when fallback is triggered (file size >= limit).","severity":"gotcha","affected_versions":"all"},{"fix":"For new projects, use asset modules: { test: /\\.png$/, type: 'asset', parser: { dataUrlCondition: { maxSize: 8192 } } }","message":"webpack 5 introduced asset modules (type: 'asset' / 'asset/inline') that supersede url-loader and file-loader. url-loader still works but is considered legacy.","severity":"deprecated","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run: npm install mime-types@latest. Or reinstall url-loader: npm install url-loader@latest.","cause":"Missing or outdated mime-types dependency (v4.0.0+ requires mime-types, not mime).","error":"Module build failed (from ./node_modules/url-loader/dist/cjs.js): TypeError: Cannot read property 'mime' of undefined"},{"fix":"Install file-loader: npm install file-loader --save-dev. Or set fallback option to an installed loader.","cause":"file-loader is not installed but is needed as fallback when files exceed limit.","error":"Error: resolve 'file-loader' ... ModuleNotFoundError: Module not found: Error: Can't resolve 'file-loader'"},{"fix":"Add rule with test: /\\.(png|jpg|gif)$/i and use 'url-loader' in webpack config.","cause":"url-loader is not configured in webpack rules or test pattern does not match .png files.","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."},{"fix":"Change option to 'esModule' (note: singular, no 's').","cause":"Using old option name 'esModules' instead of 'esModule' (renamed in v3.0.0).","error":"Configuration error: 'esModules' is not a valid option for url-loader."},{"fix":"Reinstall url-loader: npm install url-loader@latest. Or manually install: npm install schema-utils.","cause":"Missing dependency 'schema-utils' (used for option validation).","error":"Cannot find module 'schema-utils'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}