functions/partials/imagesFor.mjsjavascript
import { existsSync, readFileSync } from 'fs'
import path from 'path'
import { cacheFiles } from './cacheFiles.mjs'
import { requirePeer } from './loadPeer.mjs'
import { dest, src } from 'gulp'
import * as gulpConfig from '../../gulp.config.mjs'
const installHint = 'Add it to your project with: npm install --save-dev github:jheagle/gulp-imagemin#common-js-compatibility ' +
'(the CommonJS-compatible fork - upstream gulp-imagemin is ESM-only and cannot be require()d by this package\'s CommonJS build).'
/**
* Load `gulp-imagemin`, an optional peer dependency: image optimization is off by default and its binary-download
* dependency chain is heavy, so it is only required once the images task actually runs, and it is resolved from the
* consuming project's own directory rather than from this package.
* @memberOf module:partials
* @param {string} [projectPath=process.cwd()] - The project directory to resolve `gulp-imagemin` from.
* @returns {Function} The gulp-imagemin plugin factory.
* @throws {Error} With install instructions when gulp-imagemin is missing or is the ESM-only upstream release.
*/
export const loadImagemin = (projectPath = process.cwd()) => {
const loaded = requirePeer('gulp-imagemin', {
task: 'images',
installHint,
esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
projectPath
})
return loaded && (loaded.__esModule || loaded.default) ? loaded.default : loaded
}
/**
* Load the plugins `gulp-imagemin` exports by name (gifsicle, mozjpeg, optipng and svgo), each a promise of a plugin
* factory, for when they need options of their own (see images.jpegQuality). Resolved like {@link loadImagemin}.
* @memberOf module:partials
* @param {string} [projectPath=process.cwd()] - The project directory to resolve `gulp-imagemin` from.
* @returns {Object<string, Promise<Function>>} The plugin factories, by name.
*/
export const loadImageminPlugins = (projectPath = process.cwd()) => requirePeer('gulp-imagemin', {
task: 'images',
installHint,
esmOnlyMessage: `gulp-imagemin could not be loaded because it is ESM-only. ${installHint}`,
projectPath
})
// The plugins imagemin runs when it isn't given any, in its own order
const defaultPluginNames = ['gifsicle', 'mozjpeg', 'optipng', 'svgo']
/**
* The plugins imagemin uses by default, with mozjpeg set to the given JPEG quality instead of its own default (75).
* @memberOf module:partials
* @param {number} jpegQuality - The mozjpeg quality, 0 to 100.
* @param {Object<string, Promise<Function>>} [plugins=loadImageminPlugins()] - The plugin factories, by name.
* @returns {Array<Promise<Function>>} The plugins, in imagemin's default order.
*/
export const imageminPlugins = (jpegQuality, plugins = loadImageminPlugins()) => defaultPluginNames.map(
name => Promise.resolve(plugins[name]).then(makePlugin => name === 'mozjpeg' ? makePlugin({ quality: jpegQuality }) : makePlugin())
)
// The packages that decide imagemin's output: the wrapper and imagemin, then each plugin with the engine it runs
const imageminPackages = [
['gulp-imagemin'],
['imagemin'],
['imagemin-gifsicle', 'gifsicle'],
['imagemin-mozjpeg', 'mozjpeg'],
['imagemin-optipng', 'optipng-bin'],
['imagemin-svgo', 'svgo']
]
/**
* Find an installed package the way Node does, from a directory up through each node_modules folder. Reads the
* package.json directly, so it also works for ESM-only packages that don't export it.
* @private
* @param {string} name
* @param {string} fromDirectory
* @returns {{directory: string, version: string}|undefined}
*/
const findPackage = (name, fromDirectory) => {
for (let directory = path.resolve(fromDirectory); ; directory = path.dirname(directory)) {
const file = path.join(directory, 'node_modules', name, 'package.json')
if (existsSync(file)) {
return { directory: path.dirname(file), version: JSON.parse(readFileSync(file, 'utf8')).version }
}
if (directory === path.dirname(directory)) {
return undefined
}
}
}
/**
* The installed versions of the packages that decide imagemin's output, so the image cache stops using results made
* by older versions after an upgrade (see images.cacheDir).
* @memberOf module:partials
* @param {string} [projectPath=process.cwd()] - The project directory gulp-imagemin is installed in.
* @returns {Object<string, string>} Each package's version by name; a package that isn't installed is left out.
*/
export const imageminVersions = (projectPath = process.cwd()) => {
const gulpImagemin = findPackage('gulp-imagemin', projectPath)
const versions = {}
if (!gulpImagemin) {
return versions
}
for (const [wrapper, engine] of imageminPackages) {
const found = findPackage(wrapper, gulpImagemin.directory)
if (found) {
versions[wrapper] = found.version
const engineFound = engine && findPackage(engine, found.directory)
if (engineFound) {
versions[engine] = engineFound.version
}
}
}
return versions
}
/**
* Move and optimize images into the browser directory.
* @memberOf module:partials
* @param {string|array} [imageSrc=src/images/pattern]
* @param {string} [imageDest=dest/image/folder]
* @return {stream.Stream}
*/
export const imagesFor = (imageSrc = gulpConfig.get('images.from'), imageDest = gulpConfig.get('images.to')) => {
const imagemin = loadImagemin()
const jpegQuality = gulpConfig.get('images.jpegQuality')
// Left unset, imagemin runs its default plugins with their own defaults
const plugins = jpegQuality ? imageminPlugins(jpegQuality) : undefined
const options = {
interlaced: true,
silent: true,
verbose: false,
}
// Gulp 5 reads files as utf8 text unless told otherwise, which corrupts binary images.
return src(imageSrc, { encoding: false })
.pipe(
// Only images imagemin hasn't optimized before go through it; the rest come from the cache
cacheFiles(
imagemin(plugins, options),
{
directory: gulpConfig.get('images.cacheDir'),
// Each quality gets results of its own
name: jpegQuality ? `jpeg-quality-${jpegQuality}` : 'default',
// A new imagemin (or plugin, or engine) version, or other options, makes new results
fingerprint: JSON.stringify({ options, versions: imageminVersions() })
}
)
)
.pipe(dest(imageDest))
}