@flexis/srcset

Highly customizable tool for generating responsive images.

• Responsive images 🌠
• Optimize images with imagemin 🗜
• Convert images to modern formats such as WebP and AVIF 📸
• You can run it from the CLI ⌨️
• Works with Gulp, Webpack and as JS library 🦄

Install

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

Usage

CLI

npx srcset [...sources] [...options]
# or
yarn exec -- srcset [...sources] [...options]

Option	Description	Default
sources	Source image(s) glob patterns.	required
‑‑help, -h	Print this message.
‑‑verbose, -v	Print additional info about progress.
‑‑match, -m	Glob patern(s) or media query(ies) to match image(s) by name or size.	all images
‑‑width, -w	Output image(s) widths to resize, value less than or equal to 1 will be detected as multiplier.	no resize
‑‑format, -f	Output image(s) formats to convert.	no convert
‑‑skipOptimization	Do not optimize output images.	false
‑‑noScalingUp	Do not generate images with higher resolution than they's sources are.	false
‑‑dest, -d	Destination directory.	required

Example

srcset "src/images/*.jpg" --match "(min-width: 1920px)" --width 1920,1280,1024,860,540,320 --format jpg,webp -d static/images

Configuration

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

Constructor options

Extends common options.

Option	Type	Description	Default
concurrency	number	Concurrency limit.	os.cpus().length
limit	Limit	p-limit's limit.	pLimit(concurrency)

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]

Configuration file

Configuration file is optional. If needed, can be defined through .srcsetrc (JSON file) or .srcsetrc.js in the root directory of the project.

Supported options, extends common options:

Option	Type	Description	Default
src	string | string[]	Source image(s) glob patterns.	required
rules	IRule[]	Rules.	[]
verbose	boolean	Print additional info about progress.	false
dest	string	Destination directory.	required

Gulp

You can use @flexis/srcset with Gulp:

import srcSet from '@flexis/srcset/lib/stream';

gulp.task('images', () =>
    gulp.src('src/*.{jpg,png}')
        .pipe(srcSet([{
            match: '(min-width: 3000px)',
            width: [1920, 1280, 1024, 860, 540, 320],
            format: ['jpg', 'webp']
        }, {
            match: '(max-width: 3000px)',
            width: [1, .5],
            format: ['jpg', 'webp']
        }], {
            skipOptimization: true
        }))
        .pipe(gulp.dest('static'))
);

Plugin options:

First argument is IRule[], second argument extends common options:

Option	Type	Description	Default
verbose	boolean	Print additional info about progress.	false

JS API

Module exposes next API:

export default SrcSetGenerator;
export {
    IProcessingConfig,
    IOptimizationConfig,
    ISrcSetVinyl,
    ISize,
    IMatcherFunction,
    SupportedExtension,
    Matcher,
    IPostfixFormatter,
    Postfix,
    IConfig,
    IGenerateConfig,
    isSupportedType,
    extensions,
    attachMetadata,
    matchImage
}

Example

import {
    promises as fs
} from 'fs';
import SrcSetGenerator from '@flexis/srcset';
import Vinyl from 'vinyl';

async function generate() {
    const path = 'src/background.jpg';
    const contents = await fs.readFile(path);
    const source = new Vinyl({
        path,
        contents
    });
    const srcSet = new SrcSetGenerator();
    const images = srcSet.generate(source, {
        width: [1920, 1280, 1024, 860, 540, 320],
        format: ['jpg', 'webp']
    });

    for await (const image of images) {
        image.base = './static';
        await fs.writeFile(image.path, image.contents);
    }
}

generate();

Description of all methods you can find in Documentation.