The Complete Production SOP: How to Deploy and Run Sharp High-Speed Image Processing & WebP/AVIF Conversion in Autonomous AI Agents

---
name: "sharp-high-performance-image-process"
description: "Resize, compress, convert, and crop images at massive throughput using libvips-backed Sharp."
metadata:
  author: "Lovell Fuller"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "resize image with sharp"
  - "convert to webp sharp"
  - "generate blur placeholder sharp"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Sharp High-Speed Image Processing SOP

1. Always prefer stream piping (`fs.createReadStream().pipe(sharpInstance).pipe(dest)`) for files > 5MB.
2. When processing buffers concurrently, limit concurrency via p-limit or worker pools to prevent libvips thread exhaustion.
3. Configure libvips cache limits explicitly: `sharp.cache({ files: 50, memory: 256, items: 200 })`.
4. Always configure modern format defaults: WebP (quality: 80, effort: 4), AVIF (quality: 65, effort: 4, chromaSubsampling: '4:2:0').
5. Generate LQIP (blur placeholder) using `.resize(20, null, { fit: 'inside' }).blur(5).toBuffer()` and base64 encode.

import sharp from 'sharp';

// Optimize libvips internal memory and thread pools
sharp.concurrency(Math.max(1, Math.floor(navigator.hardwareConcurrency ? navigator.hardwareConcurrency / 2 : 2)));
sharp.cache({ memory: 256, files: 50, items: 200 });
sharp.simd(true);

export interface ImageTransformOptions {
  width?: number;
  height?: number;
  quality?: number;
  format?: 'webp' | 'avif' | 'jpeg';
}

export async function processImageStream(
  inputStream: NodeJS.ReadableStream,
  options: ImageTransformOptions = {}
): Promise<sharp.Sharp> {
  const pipeline = sharp({ failOn: 'none', sequentialRead: true });

  if (options.width || options.height) {
    pipeline.resize({
      width: options.width,
      height: options.height,
      fit: 'cover',
      withoutEnlargement: true
    });
  }

  if (options.format === 'avif') {
    pipeline.avif({ quality: options.quality ?? 65, effort: 4, chromaSubsampling: '4:2:0' });
  } else if (options.format === 'webp') {
    pipeline.webp({ quality: options.quality ?? 80, effort: 4 });
  } else {
    pipeline.jpeg({ quality: options.quality ?? 80, progressive: true });
  }

  return inputStream.pipe(pipeline);
}

import fs from 'node:fs';
import path from 'node:path';
import sharp from 'sharp';
import { processImageStream } from '../src/lib/imageProcessor';

async function verifyOutput() {
  const sampleInput = path.resolve('test/fixtures/hero.png');
  if (!fs.existsSync(sampleInput)) {
    // Create synthetic 1000x1000 fixture for testing
    await sharp({ create: { width: 1000, height: 1000, channels: 3, background: { r: 50, g: 120, b: 200 } } })
      .png()
      .toFile(sampleInput);
  }

  const readStream = fs.createReadStream(sampleInput);
  const transformer = await processImageStream(readStream, { width: 500, height: 500, format: 'webp', quality: 80 });
  const outputBuffer = await transformer.toBuffer();

  const meta = await sharp(outputBuffer).metadata();
  console.assert(meta.format === 'webp', `Expected webp, got ${meta.format}`);
  console.assert(meta.width === 500 && meta.height === 500, `Expected 500x500, got ${meta.width}x${meta.height}`);
  console.log('✅ Sharp verification suite passed successfully.');
}

verifyOutput().catch((err) => {
  console.error('❌ Verification failed:', err);
  process.exit(1);
});