url-loader
v4.1.1
A loader for webpack which transforms files into base64 URIs
0/weekUpdated 2 years agoMITUnpacked: 29.6 KB
Published by Tobias Koppers @sokra
npm install url-loader
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![chat][chat]][chat-url]
[![size][size]][size-url]
url-loader
A loader for webpack which transforms files into base64 URIs.
Getting Started
To begin, you'll need to install url-loader:
``console`
$ npm install url-loader --save-dev
url-loader works likefile-loader, but can return
a DataURL if the file is smaller than a byte limit.
index.js
`js`
import img from './image.png';
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
},
},
],
},
],
},
};
And run webpack via your preferred method.
Options
| Name | Type | Default | Description |
| :---------------------------: | :-------------------------: | :-----------------------------------------------------------: | :---------------------------------------------------------------------------------- |
| limit | {Boolean\|Number\|String} | true | Specifying the maximum size of a file in bytes. |mimetype
| | {Boolean\|String} | based from mime-types | Sets the MIME type for the file to be transformed. |encoding
| | {Boolean\|String} | base64 | Specify the encoding which the file will be inlined with. |generator
| | {Function} | () => type/subtype;encoding,base64_data | You can create you own custom implementation for encoding data. |fallback
| | {String} | file-loader | Specifies an alternative loader to use when a target file's size exceeds the limit. |esModule
| | {Boolean} | true | Use ES modules syntax. |
$3
Type: Boolean|Number|String
Default:
The limit can be specified via loader options and defaults to no limit.
#### Boolean
Enable or disable transform files into base64.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: false,
},
},
],
},
],
},
};
#### Number|String
A Number or String specifying the maximum size of a file in bytes.file-loader
If the file size is equal or greater than the limit will be used (by default) and all query parameters are passed to it.
Using an alternative to file-loader is enabled via the fallback option.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
},
},
],
},
],
},
};
$3
Type: Boolean|String
Default: based from mime-types
Specify the mimetype which the file will be inlined with.mimetype
If unspecified the value will be used from mime-types.
#### Boolean
The true value allows to generation the mimetype part from mime-types.false
The value removes the mediatype part from a Data URL (if omitted, defaults to text/plain;charset=US-ASCII).
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
mimetype: false,
},
},
],
},
],
},
};
#### String
Sets the MIME type for the file to be transformed.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
mimetype: 'image/png',
},
},
],
},
],
},
};
$3
Type: Boolean|String
Default:
Specify the encoding which the file will be inlined with.encoding
If unspecified the will be base64.
#### Boolean
If you don't want to use any encoding you can set encoding to false however if you set it to true it will use the default encoding base64.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
encoding: false,
},
},
],
},
],
},
};
#### String
It supports Node.js Buffers and Character Encodings which are ["utf8","utf16le","latin1","base64","hex","ascii","binary","ucs2"].
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
encoding: 'utf8',
},
},
],
},
],
},
};
$3
Type: Function
Default:
You can create you own custom implementation for encoding data.
webpack.config.js
`jsmimetype
module.exports = {
module: {
rules: [
{
test: /\.(png|html)$/i,
use: [
{
loader: 'url-loader',
options: {
// The and encoding arguments will be obtained from your optionsresourcePath
// The argument is path to file.data:${mimetype},${content.toString()}
generator: (content, mimetype, encoding, resourcePath) => {
if (/\.html$/i.test(resourcePath)) {
return ;
}
return data:${mimetype}${
encoding ? ;${encoding} : ''
},${content.toString(encoding)};`
},
},
},
],
},
],
},
};
$3
Type: String
Default:
Specifies an alternative loader to use when a target file's size exceeds the limit set in the limit option.
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
fallback: require.resolve('responsive-loader'),
},
},
],
},
],
},
};
The fallback loader will receive the same configuration options as url-loader.
For example, to set the quality option of a responsive-loader above use:
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
fallback: require.resolve('responsive-loader'),
quality: 85,
},
},
],
},
],
},
};
$3
Type: Boolean
Default:
By default, file-loader generates JS modules that use the ES modules syntax.
There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.
You can enable a CommonJS module syntax using:
webpack.config.js
`js`
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: 'url-loader',
options: {
esModule: false,
},
},
],
},
],
},
};
Examples
$3
SVG can be compressed into a more compact output, avoiding base64.
You can read about it more here.
You can do it using mini-svg-data-uri package.
webpack.config.js
`js
const svgToMiniDataURI = require('mini-svg-data-uri');
module.exports = {
module: {
rules: [
{
test: /\.svg$/i,
use: [
{
loader: 'url-loader',
options: {
generator: (content) => svgToMiniDataURI(content.toString()),
},
},
],
},
],
},
};
`
Contributing
Please take a moment to read our contributing guidelines if you haven't yet done so.
License
[npm]: https://img.shields.io/npm/v/url-loader.svg
[npm-url]: https://npmjs.com/package/url-loader
[node]: https://img.shields.io/node/v/url-loader.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/webpack-contrib/url-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/url-loader
[tests]: https://github.com/webpack-contrib/url-loader/workflows/url-loader/badge.svg
[tests-url]: https://github.com/webpack-contrib/url-loader/actions
[cover]: https://codecov.io/gh/webpack-contrib/url-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/url-loader
[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack
[size]: https://packagephobia.now.sh/badge?p=url-loader
[size-url]: https://packagephobia.now.sh/result?p=url-loader
`
``