responsive-loader

3.1.2 verified Sat Apr 25 auth: no javascript

A webpack loader that generates responsive images with multiple sizes and formats (including WebP and AVIF) from a single source, outputting a srcset attribute. The current stable version is 3.1.2, requiring webpack 5 and Node >=12.22.1. It offers two adapters: sharp (recommended for performance and format support) and jimp (pure JavaScript, slower but no native deps). Key differentiators include TypeScript support, flexibility with query parameters (sizes, format, quality), and easy integration with modern responsive image patterns. Release cadence is irregular, with major breaking changes in v3.0.0 moving to webpack 5 and TypeScript refactor.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. ↓

cause Missing or misconfigured loader rule in webpack config

fix

Add rule for /.(png|jpe?g)$/ with responsive-loader and set type: 'javascript/auto'.

error Error: Cannot find module 'sharp' ↓

cause Sharp is not installed (default adapter since v3.0.2)

fix

Run 'npm install sharp' or switch to jimp adapter by setting adapter: require('responsive-loader/jimp').

error yarn add sharp --ignore-engines ↓

cause Sharp may fail to install due to platform requirements

fix

Use --ignore-engines flag or switch to jimp: adapter: require('responsive-loader/jimp').

Warnings

breaking v3.0.0 dropped support for webpack 4 ↓

fix Upgrade to webpack 5 and responsive-loader >=3.0.0

breaking v3.0.0 migrated to TypeScript, module format changed ↓

fix If using CommonJS, update require path; e.g., require('responsive-loader/sharp') still works but internal structure changed.

deprecated The default adapter changed from jimp to sharp in v3.0.2 ↓

fix If relying on jimp, explicitly set adapter: require('responsive-loader/jimp') in options.

gotcha Loader expects type: 'javascript/auto' to avoid asset module doubling ↓

fix Add type: 'javascript/auto' in the loader rule (see webpack config).

gotcha Without inline query parameters, images are not processed ↓

fix Always include at least sizes[] parameter in the import path, e.g., 'image.jpg?sizes[]=600'.

Install

npm install responsive-loader

yarn add responsive-loader

pnpm add responsive-loader

Imports

default
wrong
```
import img from 'path/to/image.jpg' (no query params)
```
correct
```
import img from 'path/to/image.jpg?sizes[]=300,sizes[]=600'
```
Query parameters are used inline to specify sizes and options. Without query, loader may not apply transforms.
ResponsiveImageOutput
wrong
```
Imported as a value
```
correct
```
interface ResponsiveImageOutput { src: string; srcSet: string; ... }
```
TypeScript type, not exported from package; must be declared in a .d.ts file as shown in README.
require
wrong
```
const img = require('responsive-loader').default
```
correct
```
const img = require('path/to/image.jpg?sizes[]=300')
```
Loader handles images via webpack rule, not requiring the loader package directly. require() works as webpack processes the resource query.

Quickstart

Configures responsive-loader with sharp adapter to generate resized images (300,600,1024,2048) and placeholder, then imports an image with inline query parameters.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g)$/,
        use: {
          loader: 'responsive-loader',
          options: {
            sizes: [300, 600, 1024, 2048],
            placeholder: true,
            placeholderSize: 50,
            adapter: require('responsive-loader/sharp'),
            format: 'jpeg',
            quality: 80,
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};

// In your component (React example)
import imgSrc from 'my-image.jpg?sizes[]=300,sizes[]=600,sizes[]=1024&format=webp';
const img = <img src={imgSrc.src} srcSet={imgSrc.srcSet} sizes="(max-width: 600px) 100vw, 50vw" />;