@localnerve/gulp-images 0.1.1

package/README.md

@@ -0,0 +1,150 @@
+# @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.
+
+Reusable Gulp image-processing transforms extracted from [jam-build](https://github.com/localnerve/jam-build).
+
+Three functional groups — **optimize**, **responsive**, and **transform** — each independently importable and easily extensible.
+
+---
+
+## Installation
+
+```bash
+npm install @localnerve/gulp-images
+```
+
+Requires `gulp` as a peer dependency.
+
+---
+
+## Usage
+
+### Initialize WASM codecs first
+
+All JPEG, PNG, and WebP operations rely on WASM modules that must be initialized before any pipeline runs.
+
+```js
+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
+
+```js
+import gulp from 'gulp';
+import { initWasmModules, optimize, responsive, transform } from '@localnerve/gulp-images';
+
+await initWasmModules();
+
+const settings = {
+  prod: true,
+  svgoOptions:      { /* svgo options */ },
+  mozjpegOptions:   { quality: 80 },
+  oxipngOptions:    { level: 2 },
+  webpOptions:      { quality: 80 },
+  responsiveConfig: { /* gulp-responsive config */ }
+};
+
+const output = {}; // optional — receives image metadata from responsive + toWebp
+
+gulp.series(
+  function optimizeAndResponsive () {
+    return gulp.src('dist/images/**', { encoding: false })
+      .pipe(responsive.responsive(settings, output))
+      .pipe(optimize.svg(settings))
+      .pipe(optimize.jpeg(settings))
+      .pipe(optimize.png(settings))
+      .pipe(gulp.dest('dist/images'));
+  },
+  function convertToWebp () {
+    return gulp.src('dist/images/**', { encoding: false })
+      .pipe(transform.toWebp(settings, output))
+      .pipe(gulp.dest('dist/images'));
+  }
+)();
+```
+
+---
+
+## Groups
+
+### `optimize` — `@localnerve/gulp-images/optimize`
+
+| Export | Description |
+|--------|-------------|
+| `svg(settings)` | Optimizes SVG files via [svgo](https://github.com/svg/svgo). No-op unless `settings.prod === true`. |
+| `jpeg(settings)` | Re-encodes JPEGs via mozjpeg ([`@jsquash/jpeg`](https://github.com/jamsinclair/jSquash)). No-op unless `settings.prod === true`. |
+| `png(settings)` | Optimizes PNGs via oxipng ([`@jsquash/oxipng`](https://github.com/jamsinclair/jSquash)). No-op unless `settings.prod === true`. |
+
+**Extend the group:**
+```js
+import * as optimize from '@localnerve/gulp-images/optimize';
+const myOptimize = { ...optimize, avif: myAvifOptimizer };
+```
+
+**`settings` keys used by optimize:**
+
+| Key | Type | Used by |
+|-----|------|---------|
+| `prod` | `boolean` | all — enables optimization |
+| `svgoOptions` | `object` | `svg` |
+| `mozjpegOptions` | `object` | `jpeg` |
+| `oxipngOptions` | `object` | `png` |
+
+---
+
+### `responsive` — `@localnerve/gulp-images/responsive`
+
+| Export | Description |
+|--------|-------------|
+| `responsive(settings, output?)` | Generates responsive image variants via [`@localnerve/gulp-responsive`](https://github.com/localnerve/gulp-responsive). |
+
+`settings` - The @localnerve/gulp-responsive config defined in the [full configuration details](https://github.com/localnerve/gulp-responsive/blob/public-package/README.md#config).
+
+`output` (optional) — if supplied, variant metadata is written as:
+```js
+output[originalName][width] = { basename, mimeType }
+```
+
+**`settings` keys used:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `responsiveConfig` | `object` | Forwarded directly to `gulp-responsive` |
+
+---
+
+### `transform` — `@localnerve/gulp-images/transform`
+
+| Export | Description |
+|--------|-------------|
+| `toWebp(settings, output?)` | Converts `.jpg`, `.jpeg`, and `.png` files to `.webp` using [`@jsquash/webp`](https://github.com/jamsinclair/jSquash). |
+
+`output` (optional) — if supplied, converted file metadata is updated:
+```js
+output[key][width].basename = 'file.webp';
+output[key][width].mimeType = 'image/webp';
+```
+The `key` and `width` are derived from the filename convention `<key1>-<key2>-<width>.<ext>` (same convention as `gulp-responsive` output).
+
+**Extend the group:**
+```js
+import * as transform from '@localnerve/gulp-images/transform';
+const myTransform = { ...transform, toAvif: myAvifConverter };
+```
+
+**`settings` keys used:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `webpOptions` | `object` | Forwarded to the WebP encoder |
+
+---
+
+## License
+
+AGPL-3.0-or-later — Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@localnerve/gulp-images",
+  "version": "0.1.1",
+  "description": "Reusable gulp image processing transforms: optimize (svg, jpeg, png), responsive, and transform (toWebp).",
+  "type": "module",
+  "scripts": {
+    "lint": "eslint src/ test/",
+    "test": "node --test --experimental-test-coverage test/*.test.js",
+    "test:fixture:generate": "node test/fixtures/generate.js",
+    "check": "npm run lint && npm run test"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./optimize": "./src/optimize/index.js",
+    "./responsive": "./src/responsive/index.js",
+    "./transform": "./src/transform/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "gulp",
+    "images",
+    "optimize",
+    "responsive",
+    "webp",
+    "svg",
+    "jpeg",
+    "png",
+    "wasm"
+  ],
+  "author": "Alex Grant <info@localnerve.com> (https://www.localnerve.com)",
+  "license": "AGPL-3.0-or-later",
+  "peerDependencies": {
+    "gulp": ">=5.0.0"
+  },
+  "dependencies": {
+    "@jsquash/jpeg": "^1.4.0",
+    "@jsquash/oxipng": "^2.2.0",
+    "@jsquash/png": "^3.1.0",
+    "@jsquash/webp": "^1.5.0",
+    "@localnerve/gulp-responsive": ">=1.0.0",
+    "plugin-error": "^2.0.1",
+    "svgo": "^3.3.2",
+    "wasm-feature-detect": "^1.8.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "gulp": "^5.0.1",
+    "vinyl": "^3.0.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * @localnerve/gulp-images — top-level entry point
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ *
+ * Re-exports all three functional groups and the shared WASM initializer.
+ *
+ * Usage:
+ *   import { initWasmModules, optimize, responsive, transform } from '@localnerve/gulp-images';
+ *
+ * Or import individual groups directly:
+ *   import { svg, jpeg, png } from '@localnerve/gulp-images/optimize';
+ *   import { responsive }     from '@localnerve/gulp-images/responsive';
+ *   import { toWebp }         from '@localnerve/gulp-images/transform';
+ */
+export * as optimize    from './optimize/index.js';
+export * as responsive  from './responsive/index.js';
+export * as transform   from './transform/index.js';
+export { initWasmModules } from './utils.js';

package/src/optimize/index.js

@@ -0,0 +1,14 @@
+/**
+ * @localnerve/gulp-images — optimize group entry point
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ *
+ * Exports the built-in optimizers. Callers can extend this group by spreading:
+ *
+ *   import * as optimize from '@localnerve/gulp-images/optimize';
+ *   const myOptimize = { ...optimize, avif: myAvifFn };
+ */
+export { svg } from './svg.js';
+export { jpeg } from './jpeg.js';
+export { png } from './png.js';

package/src/optimize/jpeg.js

@@ -0,0 +1,48 @@
+/**
+ * @localnerve/gulp-images — optimize/jpeg
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ */
+import { Transform } from 'node:stream';
+import { decodeJpeg, encodeJpeg, checkSkip, log, handleError, passThrough } from '../utils.js';
+
+const pluginName = '@localnerve/optimize-jpeg';
+
+/**
+ * Gulp Transform that losslessly re-encodes JPEG files using mozjpeg (via @jsquash/jpeg).
+ * When `settings.prod` is false, files pass through unchanged.
+ *
+ * mozjpeg options reference:
+ * https://github.com/jamsinclair/jSquash/blob/main/packages/jpeg/meta.ts
+ *
+ * @param {Object} settings - Build settings
+ * @param {Object} [settings.mozjpegOptions] - Options forwarded to the mozjpeg encoder
+ * @param {boolean} settings.prod - Enable optimization only when true
+ * @returns {Transform} A Node.js Transform stream in object mode
+ */
+export function jpeg (settings) {
+  const { prod, mozjpegOptions } = settings;
+
+  if (prod) {
+    return new Transform({
+      objectMode: true,
+      transform: async (file, encoding, next) => {
+        if (checkSkip(file, ['.jpg', '.jpeg'])) { return next(null, file); }
+        if (file.isBuffer()) {
+          try {
+            const imageData = await decodeJpeg(file.contents);
+            file.contents = Buffer.from(await encodeJpeg(imageData, mozjpegOptions));
+
+            log(pluginName, file, `${file.extname.slice(1)} optimized`);
+            next(null, file);
+          } catch (error) {
+            handleError(pluginName, file, next, error);
+          }
+        }
+      }
+    });
+  }
+
+  return passThrough();
+}

package/src/optimize/png.js

@@ -0,0 +1,48 @@
+/**
+ * @localnerve/gulp-images — optimize/png
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ */
+import { Transform } from 'node:stream';
+import { decodePng, encodePng, checkSkip, log, handleError, passThrough } from '../utils.js';
+
+const pluginName = '@localnerve/optimize-png';
+
+/**
+ * Gulp Transform that optimizes PNG files using oxipng (via @jsquash/oxipng).
+ * When `settings.prod` is false, files pass through unchanged.
+ *
+ * oxipng options reference:
+ * https://github.com/jamsinclair/jSquash/blob/main/packages/oxipng/meta.ts
+ *
+ * @param {Object} settings - Build settings
+ * @param {Object} [settings.oxipngOptions] - Options forwarded to the oxipng optimizer
+ * @param {boolean} settings.prod - Enable optimization only when true
+ * @returns {Transform} A Node.js Transform stream in object mode
+ */
+export function png (settings) {
+  const { prod, oxipngOptions } = settings;
+
+  if (prod) {
+    return new Transform({
+      objectMode: true,
+      transform: async (file, encoding, next) => {
+        if (checkSkip(file, ['.png'])) { return next(null, file); }
+        if (file.isBuffer()) {
+          try {
+            const imageData = await decodePng(file.contents);
+            file.contents = Buffer.from(await encodePng(imageData, oxipngOptions));
+
+            log(pluginName, file, `${file.extname.slice(1)} optimized`);
+            next(null, file);
+          } catch (error) {
+            handleError(pluginName, file, next, error);
+          }
+        }
+      }
+    });
+  }
+
+  return passThrough();
+}

package/src/optimize/svg.js

@@ -0,0 +1,49 @@
+/**
+ * @localnerve/gulp-images — optimize/svg
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ */
+import { Transform } from 'node:stream';
+import { optimize as svgOptimize } from 'svgo';
+import { checkSkip, log, handleError, passThrough } from '../utils.js';
+
+const pluginName = '@localnerve/optimize-svg';
+
+/**
+ * Gulp Transform that optimizes SVG files using svgo.
+ * When `settings.prod` is false (non-production), files pass through unchanged.
+ *
+ * @param {Object} settings - Build settings
+ * @param {Object} [settings.svgoOptions] - Options forwarded to svgo `optimize()`
+ * @param {boolean} settings.prod - Enable optimization only when true
+ * @returns {Transform} A Node.js Transform stream in object mode
+ */
+export function svg (settings) {
+  const { prod, svgoOptions } = settings;
+
+  if (prod) {
+    return new Transform({
+      objectMode: true,
+      transform: async (file, encoding, next) => {
+        if (checkSkip(file, ['.svg'])) { return next(null, file); }
+        if (file.isBuffer()) {
+          try {
+            const result = await svgOptimize(file.contents.toString('utf8'), {
+              ...svgoOptions,
+              path: file.path
+            });
+            file.contents = Buffer.from(result.data);
+
+            log(pluginName, file, 'svg optimized');
+            next(null, file);
+          } catch (error) {
+            handleError(pluginName, file, next, error);
+          }
+        }
+      }
+    });
+  }
+
+  return passThrough();
+}

package/src/responsive/index.js

@@ -0,0 +1,65 @@
+/**
+ * @localnerve/gulp-images — responsive
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ */
+import path from 'node:path';
+import { Transform } from 'node:stream';
+import gulpResponsive from '@localnerve/gulp-responsive';
+
+/**
+ * Gulp Transform that generates responsive image variants using @localnerve/gulp-responsive.
+ *
+ * When `settings.responsiveConfig` is non-empty the transform produces resized/reformatted
+ * derivatives and—if `output` is provided—records each variant's metadata into that object
+ * (keyed by original filename without extension, then by target width):
+ *
+ *   output[name][width] = { basename, mimeType }
+ *
+ * When `settings.responsiveConfig` is empty the transform is a no-op pass-through.
+ *
+ * @param {Object} settings - Build settings
+ * @param {Object} settings.responsiveConfig - Config object forwarded to gulp-responsive
+ * @param {Object} [output] - Optional object to receive image metadata.
+ *   Treated the same as `data.images` in the original implementation.
+ * @returns {Transform} A Node.js Transform stream in object mode
+ */
+export function responsive (settings, output) {
+  const { responsiveConfig } = settings;
+
+  if (Object.keys(responsiveConfig).length > 0) {
+    const mimeTypes = {
+      '.avif':  'image/avif',
+      '.jpg':   'image/jpeg',
+      '.jpeg':  'image/jpeg',
+      '.gif':   'image/gif',
+      '.png':   'image/png',
+      '.svg':   'image/svg+xml',
+      '.webp':  'image/webp'
+      // add here as needed
+    };
+
+    return gulpResponsive(responsiveConfig, {
+      errorOnUnusedConfig: false,
+      errorOnUnusedImage:  false,
+      passThroughUnused:   true,
+      postprocess: (originalFile, config, newFile) => {
+        if (!output) { return; }
+        const key = path.parse(originalFile.relative).name;
+        if (!output[key]) {
+          output[key] = {};
+        }
+        output[key][config.width] = {
+          basename: newFile.basename,
+          mimeType: mimeTypes[newFile.extname]
+        };
+      }
+    });
+  }
+
+  return new Transform({
+    objectMode: true,
+    transform: (file, enc, next) => next(null, file)
+  });
+}

package/src/transform/index.js

@@ -0,0 +1,12 @@
+/**
+ * @localnerve/gulp-images — transform group entry point
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ *
+ * Exports the built-in image transforms. Callers can extend this group by spreading:
+ *
+ *   import * as transform from '@localnerve/gulp-images/transform';
+ *   const myTransform = { ...transform, toAvif: myAvifFn };
+ */
+export { toWebp } from './toWebp.js';

package/src/transform/toWebp.js

@@ -0,0 +1,86 @@
+/**
+ * @localnerve/gulp-images — transform/toWebp
+ *
+ * Copyright (c) 2025 Alex Grant <info@localnerve.com> (https://www.localnerve.com), LocalNerve LLC
+ * AGPL-3.0-or-later
+ */
+import path from 'node:path';
+import { Transform } from 'node:stream';
+import { decodeJpeg, decodePng, encodeWebp, checkSkip, log, handleError } from '../utils.js';
+
+const pluginName = '@localnerve/to-webp';
+
+/**
+ * Gulp Transform that converts raster images (jpg/jpeg/png) to WebP.
+ *
+ * Converted files have their extension replaced with `.webp`.  When the
+ * filename follows the `<key>-<sub>-<width>` naming convention used by
+ * gulp-responsive output AND `output` is provided, the transform also
+ * updates `output[key][width]` with the new basename and mimeType—mirroring
+ * the `data.images` updates in the original implementation.
+ *
+ * webp encoder options reference:
+ * https://github.com/jamsinclair/jSquash/blob/main/packages/webp/meta.ts
+ *
+ * @param {Object} settings - Build settings
+ * @param {Object} [settings.webpOptions] - Options forwarded to the WebP encoder
+ * @param {Object} [output] - Optional object to receive updated image metadata
+ *   (same shape written by `responsive`): output[key][width] = { basename, mimeType }
+ * @returns {Transform} A Node.js Transform stream in object mode
+ */
+export function toWebp(settings, output) {
+  const { webpOptions } = settings;
+  const exts = ['.jpg', '.jpeg', '.png'];
+  const decoders = [decodeJpeg, decodeJpeg, decodePng];
+
+  return new Transform({
+    objectMode: true,
+    transform: async (file, encoding, next) => {
+      if (checkSkip(file, exts)) {
+        return next(null, file);
+      }
+
+      if (file.isBuffer()) {
+        try {
+          const decoderIndex = exts.indexOf(file.extname.toLowerCase());
+          const originalFile = file.path;
+          const originalExt = file.extname;
+
+          // derive metadata keys from filename convention: <key-parts>-<width>
+          const name = path.parse(file.relative).name;
+          const nameParts = name.split('-');
+          const key = nameParts.slice(0, 2).join('-');
+          const width = nameParts.slice(2, 3)[0];
+
+          const imageData = await decoders[decoderIndex](file.contents);
+          file.contents = Buffer.from(await encodeWebp(imageData, webpOptions));
+
+          for (const ext of exts) {
+            file.path = file.path.replace(ext, '.webp');
+
+            if (originalFile !== file.path) {
+              // update caller-supplied output metadata if provided
+              if (output) {
+                const val = output?.[key]?.[width];
+                if (val) {
+                  val.basename = file.basename;
+                  val.mimeType = 'image/webp';
+                }
+              }
+              break; // a file won't be both .jpg and .jpeg
+            }
+          }
+
+          if (file.stat) {
+            file.stat.atime = file.stat.mtime = file.stat.ctime = new Date();
+          }
+
+          log(pluginName, file, `${originalExt.slice(1)} converted to webp`);
+          next(null, file);
+        } catch (error) {
+          handleError(pluginName, file, next, error);
+        }
+      }
+    }
+  });
+}