@flexis/srcset-loader

Highly customizable loader for generating responsive images.

• Responsive images 🌠
• Optimize images with imagemin 🗜
• Convert images to modern formats such as WebP and AVIF 📸

Install

npm i -D @flexis/srcset-loader
# or
yarn add -D @flexis/srcset-loader

Usage example

JavaScript:

import {
    groupBy,
    filterBy,
    toString
} from '@flexis/srcset-loader/runtime';
import url, {
    src,
    srcSet,
    srcMap
} from './image.jpg';

CSS:

.image {
    background-image: url('./image.jpg');
}

.webp .image {
    background-image: url('./image.jpg?{ "format": "webp" }');
}

.image.sm {
    background-image: url('./image.jpg?{ "width": 320 }');
}

Description

Src object

Option	Type	Description
id	string	Id, computed with resourceId option.
format	'avif' | 'webp' | 'jpg' | 'png' | 'gif' | 'svg'	Image file format.
type	string	Mime type of image.
width	number	Image width.
height	number	Image height.
url	string	Image url.

Loader exports

Option	Type	Description
default	string	Source image url.
src	Src	Source image.
srcSet	Src[]	Generated images.
srcMap	Record<string, string>	Id-to-url map.

Runtime exports

Located in @flexis/srcset-loader/runtime.

Option	Type	Description
groupBy	(srcSet: Src[], field: string) => [string, Src[]][]	Group images by field.
filterBy	(srcSet: Src[], field: string, value: any) => Src[]	Filter images by field value.
toString	(srcSet: Src[]) => string	Make srcset attribute string.

Query parameters

With @flexis/srcset-loader you can add query parameters to image imports. Examples:

Generate image with given rule:

import url from './image.jpg?{ "width": [1, 0.5], "format": ["webp", "jpg"] }';

Select default exportable image variant:

import url from './image.jpg?width=320';

Select default exportable image from given rule:

import url from './image.jpg?width=0.5&{ "width": [1, 0.5], "format": ["webp", "jpg"] }';

Use commonjs exports:

const url = require('./image.jpg?commonjs');

Configuration

Example:

module.exports = {
    module:  {
        rules: [{
            test: /\.jpe?g$/,
            use:  {
                loader:  '@flexis/srcset-loader',
                options: {
                    rules: [{
                        match:  '(max-width: 3000px)',
                        width:  [1, 1920, 1280, 720, 560, 320],
                        format: ['webp', 'jpg']
                    }],
                    scalingUp: false
                }
            }
        }]
    }
}

Common options

Option	Type	Description	Default
processing	Partial<IProcessingConfig>	Object with Sharp configs for each supported format.	see defaults.ts
optimization	Partial<IOptimizationConfig>	Object with imagemin plugins for each format.	see defaults.ts
skipOptimization	boolean	Do not optimize output images.	false
scalingUp	boolean	Generate images with higher resolution than they's sources are.	true
postfix	Postfix	Postfix string or function to generate postfix for image.	see defaults.ts
resourceId	Postfix	Function to generate id for image.	(width, _, format) => `${format}${width}`
generator	SrcSetGenerator	Will create set of sources form original image.	SrcSetGenerator
generatorFactory	(options) => SrcSetGenerator	Create instance of generator that will be used instead of generator from previous option. And here	undefined

Exports options

Option	Type	Description	Default
width	number	Width to match image.
format	'avif' | 'webp' | 'jpg' | 'png' | 'gif' | 'svg'	Format to match image.
commonjs	boolean	Use CommonJS exports. Notice: Vue doesn't support ES6 exports with loaders, so you should set this prop to true.	false

Rule options

Extends common options.

Option	Type	Description	Default
match	Matcher	There is support of 3 types of matchers: 1. Glob pattern of file path; 2. Media query to match image by size; 3. (path: string, size: ISize, source: Vinyl) => boolean function.	all images
format	SupportedExtension | SupportedExtension[]	Output image(s) formats to convert.	no convert
width	number | number[]	Output image(s) widths to resize, value less than or equal to 1 will be detected as multiplier.	[1]
exports	IExports	Default exported image description. Also you can pass it through query parameters. Example: background-image: url(./image.jpg?width=320&format=webp);	{}
only	boolean	Stop trying to match other rules, if this rule is matched.	false

Loader options

Extends common options.

Option	Type	Description	Default
name	string | Function	See file-loader docs. Also [postfix] placeholder is available.
outputPath	string | Function	See file-loader docs
publicPath	string | Function	See file-loader docs
context	string	See file-loader docs
emitFile	boolean	See file-loader docs	true
regExp	RegExp	See file-loader docs
processOnce	boolean	If you have multiple configurations this option will useful to process assets only once across all compilations.	false
rules	IRule[]	Rules.	[]
exports	IExports	Default exported image description. Also you can pass it through query parameters. Example: background-image: url(./image.jpg?width=320&format=webp);	{}

Using with TypeScript

Add it to your globals.d.ts:

declare module '*.jpg' {
    const url: import('@flexis/srcset-loader/types').Url;
    const src: import('@flexis/srcset-loader/types').Src;
    const srcSet: import('@flexis/srcset-loader/types').SrcSet;
    const srcMap: import('@flexis/srcset-loader/types').SrcMap;
    export default url;
    export {
        src,
        srcSet,
        srcMap
    };
}