metalsmith-optimize-images 0.12.0 → 1.0.0

package/src/processors/progressiveProcessor.js

@@ -0,0 +1,379 @@
+/**
+ * Progressive image loading processor
+ * Handles placeholder generation and smooth loading transitions
+ */
+import sharp from 'sharp';
+import path from 'node:path';
+
+/**
+ * Generate placeholder image for progressive loading
+ * Creates a small, blurred, low-quality version for instant display
+ * @param {string} imagePath - Original image path
+ * @param {Buffer} imageBuffer - Original image buffer
+ * @param {Object} placeholderConfig - Placeholder configuration (width, quality, blur)
+ * @param {Object} metalsmith - Metalsmith instance
+ * @return {Promise<Object>} Placeholder data with path and contents
+ */
+export async function generatePlaceholder(imagePath, imageBuffer, placeholderConfig, metalsmith) {
+  const { width, quality, blur } = placeholderConfig;
+
+  try {
+    // Get original image dimensions for aspect ratio calculation
+    const image = sharp(imageBuffer);
+    const metadata = await image.metadata();
+
+    // Process image: resize to small width, blur heavily, compress heavily
+    const processed = await image
+      .resize(width) // Default: 50px wide
+      .blur(blur) // Default: 10px blur
+      .jpeg({ quality }) // Default: 30% quality
+      .toBuffer();
+
+    const fileName = `${path.basename(imagePath, path.extname(imagePath))}-placeholder.jpg`;
+    const outputPath = path.join('assets/images/responsive', fileName);
+
+    return {
+      path: outputPath,
+      contents: processed,
+      fileName,
+      originalWidth: metadata.width,
+      originalHeight: metadata.height
+    };
+  } catch (error) {
+    metalsmith.debug('metalsmith-optimize-images')(`Error generating placeholder for ${imagePath}: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Create progressive wrapper HTML structure
+ * Creates a container with both placeholder and high-res images for smooth transitions
+ * @param {Object} $ - Cheerio instance
+ * @param {Object} $img - Original img element
+ * @param {Array} variants - Generated image variants
+ * @param {Object} placeholderData - Placeholder image data
+ * @param {Object} config - Plugin configuration
+ * @return {Object} Cheerio element for progressive wrapper
+ */
+export function createProgressiveWrapper($, $img, variants, placeholderData, _config) {
+  // Get original attributes
+  const alt = $img.attr('alt') || '';
+  const className = $img.attr('class') || '';
+
+  // Group variants by format - use only original format for progressive mode
+  // Progressive mode focuses on smooth loading rather than format optimization
+  const variantsByFormat = {};
+  variants.forEach((v) => {
+    if (!variantsByFormat[v.format]) {
+      variantsByFormat[v.format] = [];
+    }
+    variantsByFormat[v.format].push(v);
+  });
+
+  // Get original format variants (skip AVIF/WebP for progressive mode)
+  // JavaScript will handle format detection dynamically
+  const originalFormat = Object.keys(variantsByFormat).find((f) => f !== 'avif' && f !== 'webp');
+  const originalVariants = originalFormat ? variantsByFormat[originalFormat] : [];
+
+  if (originalVariants.length === 0) {
+    return $img.clone(); // Fallback if no variants
+  }
+
+  // Calculate aspect ratio using original image dimensions to prevent layout shift
+  // Fallback to variant dimensions if placeholderData doesn't have original dimensions
+  let aspectRatio;
+  if (placeholderData.originalWidth && placeholderData.originalHeight) {
+    aspectRatio = `${placeholderData.originalWidth}/${placeholderData.originalHeight}`;
+  } else {
+    // Fallback: use the largest variant for most accurate aspect ratio
+    const largestVariant = [...originalVariants].sort((a, b) => b.width - a.width)[0];
+    aspectRatio = `${largestVariant.width}/${largestVariant.height}`;
+  }
+
+  // Find middle-sized variant for high-res image (good balance of quality/size)
+  const highResVariant = originalVariants[Math.floor(originalVariants.length / 2)];
+
+  // Create wrapper div with modern CSS aspect-ratio
+  const $wrapper = $('<div>')
+    .addClass('responsive-wrapper js-progressive-image-wrapper')
+    .attr('style', `aspect-ratio: ${aspectRatio}`);
+
+  // Add class from original image if present
+  if (className) {
+    $wrapper.addClass(className);
+  }
+
+  // Create low-res image (placeholder) - shown immediately
+  const $lowRes = $('<img>').addClass('low-res').attr('src', `/${placeholderData.path}`).attr('alt', alt);
+
+  // Create high-res image (empty with data source) - loaded by JavaScript
+  const $highRes = $('<img>')
+    .addClass('high-res')
+    .attr('src', '')
+    .attr('alt', alt)
+    .attr('data-source', `/${highResVariant.path}`);
+
+  // Assemble the progressive wrapper
+  $lowRes.appendTo($wrapper);
+  $highRes.appendTo($wrapper);
+
+  return $wrapper;
+}
+
+/**
+ * Create standard picture element HTML
+ * Fallback function for when progressive loading fails
+ * @param {Object} $ - Cheerio instance
+ * @param {Object} $img - Original img element
+ * @param {Array} variants - Generated image variants
+ * @param {Object} config - Plugin configuration
+ * @return {Object} Cheerio element for picture
+ */
+export function createStandardPicture($, $img, variants, config) {
+  // Get original attributes
+  const src = $img.attr('src');
+  const alt = $img.attr('alt') || '';
+  const className = $img.attr('class') || '';
+  const sizesAttr = $img.attr('sizes') || config.sizes;
+
+  // Group variants by format
+  const variantsByFormat = {};
+  variants.forEach((v) => {
+    if (!variantsByFormat[v.format]) {
+      variantsByFormat[v.format] = [];
+    }
+    variantsByFormat[v.format].push(v);
+  });
+
+  // Create picture element with all formats (standard mode)
+  const $picture = $('<picture>');
+
+  // Add format-specific source elements in preference order
+  ['avif', 'webp'].forEach((format) => {
+    const formatVariants = variantsByFormat[format];
+    if (!formatVariants || formatVariants.length === 0) {
+      return;
+    }
+
+    // Sort variants by width
+    formatVariants.sort((a, b) => a.width - b.width);
+
+    // Create srcset string
+    const srcset = formatVariants.map((v) => `/${v.path} ${v.width}w`).join(', ');
+
+    // Create source element
+    $('<source>').attr('type', `image/${format}`).attr('srcset', srcset).attr('sizes', sizesAttr).appendTo($picture);
+  });
+
+  // Add original format as img element
+  const originalFormat = Object.keys(variantsByFormat).find((f) => f !== 'avif' && f !== 'webp');
+
+  if (originalFormat && variantsByFormat[originalFormat]) {
+    const formatVariants = variantsByFormat[originalFormat];
+    formatVariants.sort((a, b) => a.width - b.width);
+
+    const srcset = formatVariants.map((v) => `/${v.path} ${v.width}w`).join(', ');
+    const defaultSrc = formatVariants[Math.floor(formatVariants.length / 2)]?.path;
+
+    // Create new img element
+    const $newImg = $('<img>')
+      .attr('src', defaultSrc ? `/${defaultSrc}` : src)
+      .attr('srcset', srcset)
+      .attr('sizes', sizesAttr)
+      .attr('alt', alt)
+      .attr('loading', 'lazy');
+
+    // Add class if present
+    if (className) {
+      $newImg.attr('class', className);
+    }
+
+    // Add width/height attributes if configured and available
+    if (config.dimensionAttributes && variants.length > 0) {
+      const largestVariant = [...variants].sort((a, b) => b.width - a.width)[0];
+      $newImg.attr('width', largestVariant.width);
+      $newImg.attr('height', largestVariant.height);
+    }
+
+    $newImg.appendTo($picture);
+  }
+
+  return $picture;
+}
+
+/**
+ * Progressive image loader JavaScript
+ * Handles intersection observer, format detection, and smooth loading transitions
+ */
+export const progressiveImageLoader = `
+(function() {
+  'use strict';
+  
+  // Cache for detected format support
+  let bestFormat = null;
+  
+  // Main function called when images enter the viewport
+  const loadImage = function(entries, observer) {
+    for (let entry of entries) {
+      if (entry.isIntersecting) {
+        const thisWrapper = entry.target;
+        
+        // Find the high res image in the wrapper
+        const thisImage = thisWrapper.querySelector('.high-res');
+        const thisImageSource = thisImage.dataset.source;
+        
+        if (!thisImageSource) {
+          console.warn('No data-source found for high-res image');
+          return;
+        }
+        
+        // Apply format based on detected support
+        let finalImageSource = thisImageSource;
+        
+        if (bestFormat === 'avif') {
+          finalImageSource = thisImageSource.replace(/.(jpg|jpeg|png)$/i, '.avif');
+        } else if (bestFormat === 'webp') {
+          finalImageSource = thisImageSource.replace(/.(jpg|jpeg|png)$/i, '.webp');
+        }
+        // If 'original' or null, use original (no change needed)
+        
+        thisImage.src = finalImageSource;
+        
+        // Take this image off the observe list to prevent duplicate loading
+        observer.unobserve(thisWrapper);
+        
+        // Once the hi-res image has been loaded, add done class to trigger CSS transition
+        thisImage.onload = function() {
+          thisWrapper.classList.add('done');
+        };
+        
+        // Handle loading errors gracefully
+        thisImage.onerror = function() {
+          thisWrapper.classList.add('error');
+        };
+      }
+    }
+  };
+
+  const init = async function() {
+    // Detect best supported format first
+    bestFormat = await detectBestFormat();
+    
+    // Check for Intersection Observer support (not available in older browsers)
+    if (!('IntersectionObserver' in window)) {
+      // Fallback: load all images immediately for older browsers
+      document.querySelectorAll('.js-progressive-image-wrapper').forEach(function(wrapper) {
+        const img = wrapper.querySelector('.high-res');
+        if (img && img.dataset.source) {
+          let finalImageSource = img.dataset.source;
+          
+          // Apply detected format for fallback
+          if (bestFormat === 'avif') {
+            finalImageSource = img.dataset.source.replace(/.(jpg|jpeg|png)$/i, '.avif');
+          } else if (bestFormat === 'webp') {
+            finalImageSource = img.dataset.source.replace(/.(jpg|jpeg|png)$/i, '.webp');
+          }
+          
+          img.src = finalImageSource;
+          wrapper.classList.add('done');
+        }
+      });
+      return;
+    }
+
+    // Create intersection observer with 50px margin (loads images slightly before they're visible)
+    const observer = new IntersectionObserver(loadImage, {
+      rootMargin: '50px'
+    });
+    
+    // Loop over all image wrappers and add to intersection observer
+    const allImageWrappers = document.querySelectorAll('.js-progressive-image-wrapper');
+    for (let imageWrapper of allImageWrappers) {
+      observer.observe(imageWrapper);
+    }
+  };
+  
+  // Format detection using createImageBitmap - more reliable than canvas encoding
+  async function detectBestFormat() {
+    const fallbackFormat = 'original';
+    
+    if (!window.createImageBitmap) return fallbackFormat;
+    
+    const avifData = 'data:image/avif;base64,AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUEAAADybWV0YQAAAAAAAAAoaGRscgAAAAAAAAAAcGljdAAAAAAAAAAAAAAAAGxpYmF2aWYAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAABGgAAABYAAAAoaWluZgAAAAAAAQAAABppbmZlAgAAAAABAABhdjAxQ29sb3IAAAAAamlwcnAAAABLaXBjbwAAABRpc3BlAAAAAAAAAAEAAAABAAAAEHBpeGkAAAAAAwgICAAAAAxhdjFDgSAAAAAAABNjb2xybmNseAACAAIABoAAAAAXaXBtYQAAAAAAAAABAAEEAQKDBAAAAB5tZGF0EgAKBzgADlAgIGkyCR/wAABAAACvcA==';
+    const webpData = 'data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoCAAEAAQAcJaQAA3AA/v3AgAA=';
+    
+    try {
+      const avifBlob = await fetch(avifData).then(r => r.blob());
+      await createImageBitmap(avifBlob);
+      return 'avif';
+    } catch {
+      try {
+        const webpBlob = await fetch(webpData).then(r => r.blob());
+        await createImageBitmap(webpBlob);
+        return 'webp';
+      } catch {
+        return fallbackFormat;
+      }
+    }
+  }
+
+  // Initialize when DOM is ready
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+
+})();
+`;
+
+/**
+ * Progressive image CSS styles
+ * Handles aspect ratio, positioning, and smooth transitions between placeholder and high-res images
+ */
+export const progressiveImageCSS = `
+.responsive-wrapper {
+  position: relative;
+  overflow: hidden;
+  background-color: #f0f0f0;
+}
+
+.responsive-wrapper .low-res {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: opacity 0.4s ease;
+}
+
+.responsive-wrapper .high-res {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  opacity: 0;
+  transition: opacity 0.4s ease;
+}
+
+.responsive-wrapper.done .high-res {
+  opacity: 1;
+}
+
+.responsive-wrapper.done .low-res {
+  opacity: 0;
+}
+
+.responsive-wrapper.error .low-res {
+  filter: none;
+}
+
+/* Ensure images are responsive */
+.responsive-wrapper img {
+  max-width: 100%;
+  height: auto;
+}
+`;

package/src/utils/config.js

@@ -0,0 +1,117 @@
+/**
+ * Configuration utility for the plugin
+ * Handles merging user options with sensible defaults
+ */
+
+/**
+ * Deep merge for objects. Handles nested objects properly, which is needed for
+ * the formatOptions and placeholder options. Implemented as a plain loop rather
+ * than a spread-into-reduce accumulator to avoid quadratic copying.
+ * @param {Object} target - Target object
+ * @param {Object} source - Source object
+ * @return {Object} - Merged result
+ */
+const deepMerge = (target, source) => {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    result[key] = source[key]?.constructor === Object ? deepMerge(target[key] || {}, source[key]) : source[key];
+  }
+  return result;
+};
+
+/**
+ * Builds configuration with sensible defaults
+ * @param {Object} options - User provided plugin options
+ * @return {Object} - Complete config with defaults
+ */
+export function buildConfig(options = {}) {
+  // Default configuration with sensible defaults
+  const defaults = {
+    // Responsive breakpoints to generate
+    widths: [320, 640, 960, 1280, 1920],
+
+    // Formats to generate in order of preference (first is most preferred)
+    formats: ['avif', 'webp', 'original'],
+
+    // Format-specific compression settings
+    formatOptions: {
+      avif: { quality: 65, speed: 5 }, // Better compression but slower
+      webp: { quality: 80, lossless: false },
+      jpeg: { quality: 85, progressive: true },
+      png: { compressionLevel: 8, palette: true }
+    },
+
+    // Which HTML files to process
+    htmlPattern: '**/*.html',
+
+    // CSS selector for images to process
+    imgSelector: 'img:not([data-no-responsive])',
+
+    // Output directory for processed images (relative to Metalsmith destination)
+    outputDir: 'assets/images/responsive',
+
+    // Output naming pattern
+    // Available tokens: [filename], [width], [format], [hash]
+    outputPattern: '[filename]-[width]w-[hash].[format]',
+
+    // Whether to skip generating sizes larger than original
+    skipLarger: true,
+
+    // Add loading="lazy" to images
+    lazy: true,
+
+    // Add width and height attributes to prevent layout shift
+    dimensionAttributes: true,
+
+    // Default sizes attribute value for responsive images
+    sizes: '(max-width: 768px) 100vw, 75vw',
+
+    // Maximum number of images to process in parallel
+    concurrency: 5,
+
+    // Whether to generate a metadata JSON file
+    generateMetadata: false,
+
+    // Progressive loading options
+    isProgressive: false, // TODO: Debug timeout issue in tests
+
+    // Placeholder image settings for progressive loading
+    placeholder: {
+      width: 50,
+      quality: 30,
+      blur: 10
+    },
+
+    // Background image processing settings
+    processUnusedImages: true, // Process images not found in HTML for background use
+    imagePattern: '**/*.{jpg,jpeg,png,gif,webp,avif}', // Pattern to find images for background processing
+
+    // Persistent cache directory for generated variants (relative to metalsmith.directory())
+    // false = disabled, true = default path ('lib/<outputDir>'), string = custom path
+    // When set, variants are written to this directory and loaded from it on subsequent builds.
+    // Commit this directory to git so CI/Netlify never needs to run Sharp.
+    cache: false
+  };
+
+  // Special handling for formatOptions to ensure deep merging
+  // This allows users to override specific format settings without losing defaults
+  // e.g., { formatOptions: { jpeg: { quality: 90 } } } only changes JPEG quality
+  if (options && options.formatOptions) {
+    options = {
+      ...options,
+      formatOptions: deepMerge(defaults.formatOptions, options.formatOptions)
+    };
+  }
+
+  // Special handling for placeholder options to ensure deep merging
+  // Allows partial placeholder config like { placeholder: { width: 100 } }
+  if (options && options.placeholder) {
+    options = {
+      ...options,
+      placeholder: deepMerge(defaults.placeholder, options.placeholder)
+    };
+  }
+
+  // Merge the defaults with user options
+  return { ...defaults, ...(options || {}) };
+}

package/src/utils/hash.js

@@ -0,0 +1,17 @@
+/**
+ * Utility for generating content hashes
+ * Used for cache-busting - ensures filenames change when image content changes
+ */
+import crypto from 'node:crypto';
+
+/**
+ * Generates a short hash based on image content
+ * Creates an 8-character hash for cache-busting in filenames
+ * @param {Buffer} buffer - The image buffer
+ * @return {string} - A short hash string (8 characters)
+ */
+export function generateHash(buffer) {
+  // SHA-256 for cache-busting - using secure algorithm to satisfy security scanners
+  // Only use first 8 characters to keep filenames manageable
+  return crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 8);
+}

package/src/utils/paths.js

@@ -0,0 +1,35 @@
+/**
+ * Path utilities for image variants
+ * Handles the filename pattern system with token replacement
+ */
+import path from 'node:path';
+
+/**
+ * Generate variant filename using pattern
+ * Applies token replacement to create output filenames
+ * Tokens: [filename], [width], [format], [hash]
+ * @param {string} originalPath - Original image path
+ * @param {number} width - Target width
+ * @param {string} format - Target format ('original' means keep source format)
+ * @param {string} hash - Content hash for cache busting
+ * @param {object} config - Plugin config options
+ * @return {string} - Generated path relative to Metalsmith destination
+ */
+export function generateVariantPath(originalPath, width, format, hash, config) {
+  const parsedPath = path.parse(originalPath);
+  const originalFormat = parsedPath.ext.slice(1).toLowerCase();
+
+  // If format is 'original', use the source format (e.g., 'jpeg' for image.jpg)
+  const outputFormat = format === 'original' ? originalFormat : format;
+
+  // Apply pattern replacements using the tokens system
+  // Default pattern: '[filename]-[width]w-[hash].[format]'
+  // Results in: 'image-320w-abc12345.webp'
+  const outputName = config.outputPattern
+    .replace('[filename]', parsedPath.name)
+    .replace('[width]', width)
+    .replace('[format]', outputFormat)
+    .replace('[hash]', hash || '');
+
+  return path.join(config.outputDir, outputName);
+}