@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}` |

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
    };
}