Gulp-html-php-picture NPM

gulp-html-php-picture

Gulp plugin to wrap tag <img> with <picture> adding <source> including .avif and .webp and sort sources inside <picture> by size

The Idea of Plugin

I checked all popular packages that wrapping <img> with <picture> and combined them all in one with extra options & parameters like: sorting by size, adding custom image extenstions, ignoring certain image(s)

A list of packages that inspired me. You can check them out if you need more similar / simpler solutions

Features

No deprecated gulp-util!
Compitable with PHP <img src="<?php ...(); ?>/img/image.jpg" alt="Example">
Works with any format if <img> tag (no need to write tag in one line, it can be tabulated)
Adds <source> with .avif & .webp by default ( can be adjusted in parameters ) and possibility to add custom image extensions
Ignore <img> inside HTML Comments
Ignore <img> inside <script></script> that inlined into html
Ignore existing <picture> tags
Option to add a class for the <picture> tag after building the project using a special attribute <img data-picture-class="picture-wrapper"> in the source code
Option to sort sources inside <picture> by their size to force browser download the smallest one
Option to remove <sources> with incorrect or unexisted src attribute
Possibility not to wrap certain image(s) with special attribute or class name <img data-ignore class="img-ignore" src="" alt="">

Install

$ npm i --save-dev gulp-html-php-picture

Usage

Use this into your gulpfile.js:

const gulp = require('gulp')
const imgToPicture = require("gulp-html-php-picture")

function html() {
    return src('src/*.html')
        .pipe(imgToPicture({
            imgFolder: './dist',
        }))
        .pipe(gulp.dest('dist/'))
}

exports.html = html;

with modern ES6 modules syntax:

import gulp from "gulp"
import imgToPicture from "gulp-html-php-picture"

const html = () => {
    return src('src/*.html')
        .pipe(imgToPicture({
            imgFolder: './dist',
        }))
        .pipe(gulp.dest('dist/'))
}

exports.html = html;

Recommended to use with gulp-plumber :

import gulp from "gulp"
import plumber from "gulp-plumber"
import imgToPicture from "gulp-html-php-picture"

const html = () => {
    return src('src/*.html')
        .pipe(plumber({
            errorHandler: function (err) {
                notify.onError({
                    title: "HTML Error",
                    message: "<%= error.message %>"
                })(err)
            }
        }))
        .pipe(imgToPicture({
            imgFolder: './dist',
        }))
        .pipe(gulp.dest('dist/'))
}

exports.html = html;

Parameters | Options

imgToPicture({
    imgFolder: './dist', // required for sorting by size
    extensions: ['.jpg', '.jpeg', '.png'],
    ignoreClassname: 'img-ignore',
    ignoreAttribute: 'data-ignore',
    pictureClassAttribute: 'data-picture-class',
    logger: true,
    sortBySize: true,
    ignoreScripts: true,
    ignoreComments: true,
    filterUnexistedImages: true,
    sourceExtensions: [
        {
            extension: 'avif',
            mimetype: 'image/avif',
        },
        {
            extension: 'webp',
            mimetype: 'image/webp',
        },
    ],
})

Options

imgFolder

Type: string Default: false

Pass an relative path to build folder where images are located. It's required only parameter in case you want to use sorting by image size In my Gulp Boilerplate it's './dist'

extensions

Type: array[] Default: ['.jpg', '.jpeg', '.png']

Pass an array of image extensions you want to wrap with <picture>

ignoreClassname

Type: string Default: 'img-ignore'

The images with this class name won't be wrapped with <picture>

ignoreAttribute

Type: string Default: 'data-ignore'

The images with this attribute won't be wrapped with <picture>