or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-url-loader

A webpack loader that transforms files into base64 URIs for efficient bundling

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/url-loader@4.1.x

To install, run

npx @tessl/cli install tessl/npm-url-loader@4.1.0

index.mddocs/

URL Loader

URL Loader is a webpack loader that transforms files into base64 URIs for efficient bundling and deployment. It works as an intelligent alternative to file-loader by converting small files directly into data URLs while falling back to file-loader for larger files that exceed a configurable size limit.

Package Information

  • Package Name: url-loader
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install url-loader
  • Webpack Versions: 4.x and 5.x
  • Node.js: >= 10.13.0

Core Imports

For webpack configuration:

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

For programmatic usage (rare):

const urlLoader = require('url-loader');

Basic Usage

URL Loader is primarily used through webpack configuration. It automatically processes matched files during the webpack build process:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: false, // Always use base64
            },
          },
        ],
      },
      {
        test: /\.svg$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192, // 8KB threshold
              mimetype: 'image/svg+xml',
              encoding: 'base64',
            },
          },
        ],
      },
    ],
  },
};

Application code using processed assets:

import logoImage from './assets/logo.png'; // Will be base64 data URI if under limit
import iconSvg from './assets/icon.svg';   // Will be base64 data URI if under limit

// logoImage and iconSvg contain either:
// - data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... (if under limit)
// - /static/media/logo.abc123.png (if over limit, handled by fallback)

Architecture

URL Loader operates as a webpack loader with the following key components:

  • Main Loader Function: Processes file content and determines transformation strategy
  • Size-based Decision Logic: Compares file size against configurable limit
  • Data URI Generation: Converts files to base64 or other encoding formats
  • Fallback System: Delegates to another loader (typically file-loader) for large files
  • Configuration Validation: Validates all options against JSON schema

Capabilities

Main Loader Function

The primary webpack loader function that processes file content.

/**
 * Main webpack loader function - called by webpack during build
 * @param {Buffer|string} content - File content to process
 * @returns {string} JavaScript module code containing the data URI or fallback result
 */
function loader(content) {}

// Raw mode flag - indicates loader should receive Buffer instead of string
loader.raw = true;

Configuration Options

Complete configuration interface for the loader options.

interface LoaderOptions {
  /** Maximum file size for base64 transformation */
  limit?: boolean | number | string;
  /** Encoding method for data URI generation */
  encoding?: boolean | "utf8" | "utf16le" | "latin1" | "base64" | "hex" | "ascii" | "binary" | "ucs2";
  /** MIME type for the generated data URI */
  mimetype?: boolean | string;
  /** Custom data URI generator function */
  generator?: (content: Buffer, mimetype: string, encoding: string, resourcePath: string) => string;
  /** Alternative loader for files exceeding the limit */
  fallback?: string | FallbackConfig;
  /** Generate ES module syntax instead of CommonJS */
  esModule?: boolean;
}

interface FallbackConfig {
  /** Fallback loader name */
  loader: string;
  /** Options to pass to fallback loader */
  options?: object | string;
}

Limit Configuration

Controls when files are transformed to base64 vs delegated to fallback loader.

// Boolean mode
limit: true   // Always transform to base64
limit: false  // Never transform, always use fallback

// Numeric mode (bytes)
limit: 8192   // Transform files <= 8KB
limit: "10kb" // Transform files <= 10KB (string format)

Usage Examples:

// Always convert to base64 (no size limit)
{
  loader: 'url-loader',
  options: {
    limit: true
  }
}

// Never convert to base64 (always use fallback)
{
  loader: 'url-loader',
  options: {
    limit: false
  }
}

// Size-based conversion (8KB threshold)
{
  loader: 'url-loader',
  options: {
    limit: 8192
  }
}

MIME Type Configuration

Controls the MIME type included in generated data URIs.

// Boolean mode
mimetype: true  // Auto-detect from file extension
mimetype: false // Omit MIME type from data URI

// String mode
mimetype: "image/png" // Use specific MIME type

Usage Examples:

// Auto-detect MIME type
{
  loader: 'url-loader',
  options: {
    mimetype: true // Uses mime-types library
  }
}

// Specific MIME type
{
  loader: 'url-loader',
  options: {
    mimetype: 'image/svg+xml'
  }
}

// No MIME type in data URI
{
  loader: 'url-loader',
  options: {
    mimetype: false
  }
}

Encoding Configuration

Specifies how file content is encoded in the data URI.

// Boolean mode
encoding: true  // Use base64 encoding
encoding: false // No encoding (raw content)

// String mode - Node.js buffer encodings
encoding: "base64" | "utf8" | "utf16le" | "latin1" | "hex" | "ascii" | "binary" | "ucs2"

Usage Examples:

// Base64 encoding (default)
{
  loader: 'url-loader',
  options: {
    encoding: 'base64'
  }
}

// UTF-8 encoding for text files
{
  loader: 'url-loader',
  options: {
    encoding: 'utf8'
  }
}

// No encoding
{
  loader: 'url-loader',
  options: {
    encoding: false
  }
}

Custom Generator Function

Allows custom data URI generation logic.

/**
 * Custom generator function for creating data URIs
 * @param {Buffer} content - File content as Buffer
 * @param {string} mimetype - Resolved MIME type
 * @param {string} encoding - Resolved encoding method
 * @param {string} resourcePath - Full file path
 * @returns {string} Custom data URI string
 */
type GeneratorFunction = (
  content: Buffer,
  mimetype: string,
  encoding: string,
  resourcePath: string
) => string;

Usage Examples:

{
  loader: 'url-loader',
  options: {
    generator: (content, mimetype, encoding, resourcePath) => {
      // Custom logic for HTML files
      if (/\.html$/i.test(resourcePath)) {
        return `data:${mimetype},${content.toString()}`;
      }
      
      // Default behavior for other files
      return `data:${mimetype}${encoding ? `;${encoding}` : ''},${content.toString(encoding)}`;
    }
  }
}

Fallback Loader Configuration

Configures alternative loader for files exceeding the size limit.

// String format
fallback: "file-loader"
fallback: "responsive-loader"

// Object format with options
fallback: {
  loader: "file-loader",
  options: {
    name: "[name].[hash:8].[ext]",
    outputPath: "images/"
  }
}

Usage Examples:

// Simple fallback
{
  loader: 'url-loader',
  options: {
    limit: 8192,
    fallback: 'file-loader'
  }
}

// Fallback with custom options
{
  loader: 'url-loader',
  options: {
    limit: 8192,
    fallback: {
      loader: 'file-loader',
      options: {
        name: '[path][name].[ext]',
        outputPath: 'assets/'
      }
    }
  }
}

// Advanced fallback
{
  loader: 'url-loader',
  options: {
    limit: 8192,
    fallback: require.resolve('responsive-loader'),
    quality: 85 // This option passes through to responsive-loader
  }
}

ES Module Configuration

Controls output module format.

esModule: boolean // Default: true

Usage Examples:

// ES module output (default)
{
  loader: 'url-loader',
  options: {
    esModule: true
  }
}
// Generates: export default "data:image/png;base64,..."

// CommonJS output
{
  loader: 'url-loader',
  options: {
    esModule: false
  }
}
// Generates: module.exports = "data:image/png;base64,..."

Error Handling

URL Loader validates all options and throws errors for:

  • Invalid Options: Schema validation failures for malformed configuration
  • Missing Fallback: When fallback loader cannot be resolved or loaded
  • Encoding Errors: When specified encoding is not supported by Node.js
  • File System Errors: When file cannot be read during processing

Common error scenarios:

// Invalid limit type
{
  loader: 'url-loader',
  options: {
    limit: {} // Error: limit must be boolean, number, or string
  }
}

// Invalid encoding
{
  loader: 'url-loader',
  options: {
    encoding: 'invalid' // Error: unsupported encoding
  }
}

// Missing fallback loader
{
  loader: 'url-loader',
  options: {
    fallback: 'nonexistent-loader' // Error: cannot resolve loader
  }
}

Dependencies

Required Dependencies

  • loader-utils (^2.0.0): Webpack loader utilities for option parsing
  • mime-types (^2.1.27): MIME type detection from file extensions
  • schema-utils (^3.0.0): JSON schema validation for loader options

Peer Dependencies

  • webpack (^4.0.0 || ^5.0.0): Required webpack version
  • file-loader (*): Optional, used as default fallback loader

Runtime Requirements

  • Node.js: >= 10.13.0
  • Environment: Node.js server-side (webpack build process)

CommonJS and ES Module Support

URL Loader provides both CommonJS and ES module interfaces:

// CommonJS (main entry - dist/cjs.js)
const urlLoader = require('url-loader');
urlLoader.raw; // true

// ES Module (source - src/index.js)
import urlLoader, { raw } from 'url-loader/src';

Note: The ES module version is the source code and requires transpilation for older Node.js versions.