Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    url-loader

    4.1.1¬†‚Äʬ†Public¬†‚Äʬ†Published

    npm node deps tests chat size

    url-loader

    A loader for webpack which transforms files into base64 URIs.

    Getting Started

    To begin, you'll need to install url-loader:

    $ npm install url-loader --save-dev

    url-loader works like file-loader, but can return a DataURL if the file is smaller than a byte limit.

    index.js

    import img from './image.png';

    webpack.config.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.

    limit

    Type: Boolean|Number|String Default: undefined

    The limit can be specified via loader options and defaults to no limit.

    Boolean

    Enable or disable transform files into base64.

    webpack.config.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. If the file size is equal or greater than the limit file-loader 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

    module.exports = {
      module: {
        rules: [
          {
            test: /\.(png|jpg|gif)$/i,
            use: [
              {
                loader: 'url-loader',
                options: {
                  limit: 8192,
                },
              },
            ],
          },
        ],
      },
    };

    mimetype

    Type: Boolean|String Default: based from mime-types

    Specify the mimetype which the file will be inlined with. If unspecified the mimetype value will be used from mime-types.

    Boolean

    The true value allows to generation the mimetype part from mime-types. The false value removes the mediatype part from a Data URL (if omitted, defaults to text/plain;charset=US-ASCII).

    webpack.config.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

    module.exports = {
      module: {
        rules: [
          {
            test: /\.(png|jpg|gif)$/i,
            use: [
              {
                loader: 'url-loader',
                options: {
                  mimetype: 'image/png',
                },
              },
            ],
          },
        ],
      },
    };

    encoding

    Type: Boolean|String Default: base64

    Specify the encoding which the file will be inlined with. If unspecified the encoding 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

    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

    module.exports = {
      module: {
        rules: [
          {
            test: /\.svg$/i,
            use: [
              {
                loader: 'url-loader',
                options: {
                  encoding: 'utf8',
                },
              },
            ],
          },
        ],
      },
    };

    generator

    Type: Function Default: (mimetype, encoding, content, resourcePath) => mimetype;encoding,base64_content

    You can create you own custom implementation for encoding data.

    webpack.config.js

    module.exports = {
      module: {
        rules: [
          {
            test: /\.(png|html)$/i,
            use: [
              {
                loader: 'url-loader',
                options: {
                  // The `mimetype` and `encoding` arguments will be obtained from your options
                  // The `resourcePath` argument is path to file.
                  generator: (content, mimetype, encoding, resourcePath) => {
                    if (/\.html$/i.test(resourcePath)) {
                      return `data:${mimetype},${content.toString()}`;
                    }
     
                    return `data:${mimetype}${
                      encoding ? `;${encoding}` : ''
                    },${content.toString(encoding)}`;
                  },
                },
              },
            ],
          },
        ],
      },
    };

    fallback

    Type: String Default: 'file-loader'

    Specifies an alternative loader to use when a target file's size exceeds the limit set in the limit option.

    webpack.config.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

    module.exports = {
      module: {
        rules: [
          {
            test: /\.(png|jpg|gif)$/i,
            use: [
              {
                loader: 'url-loader',
                options: {
                  fallback: require.resolve('responsive-loader'),
                  quality: 85,
                },
              },
            ],
          },
        ],
      },
    };

    esModule

    Type: Boolean Default: true

    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

    module.exports = {
      module: {
        rules: [
          {
            test: /\.css$/,
            use: [
              {
                loader: 'url-loader',
                options: {
                  esModule: false,
                },
              },
            ],
          },
        ],
      },
    };

    Examples

    SVG

    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

    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.

    CONTRIBUTING

    License

    MIT

    
    

    Keywords

    Install

    npm i url-loader

    DownloadsWeekly Downloads

    8,012,294

    Version

    4.1.1

    License

    MIT

    Unpacked Size

    29.6 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar