@localnerve/gulp-images

Portable (wasm & sharp), minimal dependency, streaming image processing for javascript builds. Optionally outputs image processing metadata to allow the images themselves to drive css generation and/or other work. Eventually, this project will be wasm only, no build chain required.

Offers Jpeg-xl optimization and transformations.

Three functional groups — optimize, responsive, and transform — each independently importable and easily extensible.

Installation

npm install @localnerve/gulp-images

Requires gulp as a peer dependency.

Usage

Initialize WASM codecs first

All optimize and transform operations rely on WASM modules that must be initialized before any pipeline runs.

import { initWasmModules } from '@localnerve/gulp-images';

// Use process.cwd() (default) or pass an explicit base path:
await initWasmModules();                        // looks for node_modules relative to cwd
await initWasmModules('/path/to/monorepo/root'); // explicit base path

Full pipeline example

Generates responsive images, then optimizes all images, then creates webp versions of all raster images.

import gulp from 'gulp';
import { initWasmModules, optimize, responsive, transform } from '@localnerve/gulp-images';

await initWasmModules();

const settings = {
  prod: true,
  svgoOptions:      { /* svgo options */ },
  avifOptions:      { quality: 80, speed: 6 },
  jxlOptions:       { quality: 80 },
  mozjpegOptions:   { quality: 80 },
  oxipngOptions:    { level: 2 },
  webpOptions:      { quality: 80 },
  responsiveConfig: { /* gulp-responsive config */ }
};

const output = {}; // optional — receives image metadata from responsive + transform

gulp.series(
  function createResponsiveImages () {
    return gulp.src('dist/images/**', { encoding: false })
      .pipe(responsive.responsive(settings, output))
      .pipe(gulp.dest('dist/images'));
  }
  function optimizeImages () {
    return gulp.src('dist/images/**', { encoding: false })
      .pipe(optimize.svg(settings))
      .pipe(optimize.avif(settings))
      .pipe(optimize.jpeg(settings))
      .pipe(optimize.jxl(settings))
      .pipe(optimize.png(settings))
      .pipe(gulp.dest('dist/images'));
  },
  function convertToWebp () {
    return gulp.src('dist/images/**', { encoding: false })
      .pipe(transform.toWebp(settings, output)) // toAvif, toJxl available
      .pipe(gulp.dest('dist/images'));
  }
)();

Groups

optimize — @localnerve/gulp-images/optimize

| Export | Description | |--------|-------------| | svg(settings) | Optimizes SVG files via svgo. No-op unless settings.prod === true. | | jpeg(settings) | Re-encodes JPEGs via mozjpeg (@jsquash/jpeg). No-op unless settings.prod === true. | | png(settings) | Optimizes PNGs via oxipng (@jsquash/oxipng). No-op unless settings.prod === true. | | avif(settings) | Optimizes AVIFs via libavif (@jsquash/avif). No-op unless settings.prod === true. | | jxl(settings) | Optimizes JXLs via libjxl (@jsquash/jxl). No-op unless settings.prod === true. | | webp(settings) | Optimizes WEBPs via libwebp (@jsquash/webp). No-op unless settings.prod === true. |

settings keys used by optimize:

| Key | Type | Used by | Reference | |-----|------|---------|-----------------| | prod | boolean | all — enables optimization | This Doc | | svgoOptions | object | svg | reference | | mozjpegOptions | object | jpeg | reference | | oxipngOptions | object | png | reference | | avifOptions | object | avif | reference | | jxlOptions | object | jxl | reference | | webpOptions | object | webp | reference |

responsive — @localnerve/gulp-images/responsive

| Export | Description | |--------|-------------| | responsive(settings, output?) | Generates responsive image variants via @localnerve/gulp-responsive. |

settings - The @localnerve/gulp-responsive config defined in the full configuration details.

output (optional) — if supplied, variant metadata is written as:

output[originalName][width] = { basename, mimeType }

settings keys used:

| Key | Type | Description | Reference | |-----|------|-------------|-----------| | responsiveConfig | object | Forwarded directly to gulp-responsive | reference |

transform — @localnerve/gulp-images/transform

| Export | Description | |--------|-------------| | toWebp(settings, output?) | Converts .avif, .jpg, .jpeg, .jxl and .png files to .webp using @jsquash/webp. | | toAvif(settings, output?) | Converts .jpg, .jpeg, .jxl, .png, and .webp files to .avif using @jsquash/avif. | | toJxl(settings, output?) | Converts .avif, .jpg, .jpeg, .png, and .webp files to .jxl using @jsquash/jxl. |

output (optional) — if supplied, converted file metadata is updated:

// example output created for `toWebp`:
output[key][width].basename = 'file.webp';
output[key][width].mimeType = 'image/webp';

The key and width are derived from the input image filename convention <key1>-<key2>-<width>.<ext> (same convention as gulp-responsive output).

settings keys used:

| Key | Type | Description | Reference | |-----|------|-------------|-----------| | webpOptions | object | Forwarded to the WebP encoder | reference | | avifOptions | object | Forwarded to the Avif encoder | reference | | jxlOptions | object | Forwarded to the Jxl encoder | reference |

License

AGPL-3.0-or-later — Copyright (c) 2025 Alex Grant [email protected] (https://www.localnerve.com), LocalNerve LLC