Processing Images

Quick Start

import sharp from 'sharp';

// Resize and optimize for web async function optimizeImage(inputPath: string, outputPath: string): Promise<void> { await sharp(inputPath) .resize(1200, 1200, { fit: 'inside', withoutEnlargement: true }) .webp({ quality: 80 }) .toFile(outputPath); }

// Generate thumbnail with smart crop async function generateThumbnail(inputPath: string, outputPath: string): Promise<void> { await sharp(inputPath) .resize(300, 300, { fit: 'cover', position: sharp.strategy.attention }) .jpeg({ quality: 85 }) .toFile(outputPath); }

// Convert to multiple formats async function convertFormats(inputPath: string, outputDir: string): Promise<void> { const baseName = path.basename(inputPath, path.extname(inputPath)); await Promise.all([ sharp(inputPath).webp({ quality: 80 }).toFile(${outputDir}/${baseName}.webp), sharp(inputPath).avif({ quality: 70 }).toFile(${outputDir}/${baseName}.avif), sharp(inputPath).jpeg({ quality: 85, mozjpeg: true }).toFile(${outputDir}/${baseName}.jpg), ]); }

Features

Feature Description Guide

Resizing Scale images with various fit modes Use resize() with cover, contain, fill, inside, outside

Format Conversion Convert between JPEG, PNG, WebP, AVIF Use toFormat() or format-specific methods

Optimization Reduce file size while preserving quality Set quality levels and use mozjpeg/effort options

Smart Cropping Auto-detect focal points for cropping Use sharp.strategy.attention for smart positioning

Effects Apply blur, sharpen, grayscale, tint Use blur(), sharpen(), grayscale(), tint()

Watermarks Add text or image overlays Use composite() with SVG or image buffers

Metadata Read EXIF data and image dimensions Use metadata() for width, height, format info

Color Analysis Extract dominant colors Use raw() output with color quantization

LQIP Generation Create low-quality image placeholders Resize to ~20px with blur for base64 preview

Batch Processing Process multiple images concurrently Use p-queue with controlled concurrency

Common Patterns

Responsive Image Set Generation

async function generateResponsiveSet( inputPath: string, outputDir: string, widths: number[] = [320, 640, 1024, 1920] ): Promise<{ srcset: string; sizes: string }> { const baseName = path.basename(inputPath, path.extname(inputPath)); const srcsetParts: string[] = [];

for (const width of widths) { const filename = ${baseName}-${width}w.webp; await sharp(inputPath) .resize(width, null, { withoutEnlargement: true }) .webp({ quality: 80 }) .toFile(path.join(outputDir, filename)); srcsetParts.push(${filename} ${width}w); }

return { srcset: srcsetParts.join(', '), sizes: '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw', }; }

E-commerce Product Image Processing

async function processProductImage(inputPath: string, productId: string): Promise<ProductImages> { const outputDir = path.join(MEDIA_DIR, 'products', productId); await fs.mkdir(outputDir, { recursive: true });

const sizes = [ { name: 'thumb', width: 150, height: 150 }, { name: 'small', width: 300, height: 300 }, { name: 'medium', width: 600, height: 600 }, { name: 'large', width: 1200, height: 1200 }, ];

const images: Record<string, string> = {}; for (const size of sizes) { const outputPath = path.join(outputDir, ${size.name}.webp); await sharp(inputPath) .resize(size.width, size.height, { fit: 'contain', background: '#ffffff' }) .webp({ quality: 85 }) .toFile(outputPath); images[size.name] = /media/products/${productId}/${size.name}.webp; }

// Generate LQIP placeholder const lqipBuffer = await sharp(inputPath).resize(20).blur(5).jpeg({ quality: 20 }).toBuffer(); const lqip = data:image/jpeg;base64,${lqipBuffer.toString('base64')};

return { images, lqip }; }

Image Watermarking

async function addWatermark(inputPath: string, outputPath: string, watermarkPath: string): Promise<void> { const metadata = await sharp(inputPath).metadata(); const watermark = await sharp(watermarkPath) .resize(Math.round((metadata.width || 800) * 0.2)) .toBuffer();

await sharp(inputPath) .composite([{ input: watermark, gravity: 'southeast', blend: 'over' }]) .toFile(outputPath); }

async function addTextWatermark(inputPath: string, outputPath: string, text: string): Promise<void> { const metadata = await sharp(inputPath).metadata(); const { width = 800, height = 600 } = metadata;

const svg = <svg width="${width}" height="${height}"> <text x="${width - 20}" y="${height - 20}" text-anchor="end" font-size="24" fill="white" opacity="0.5">${text}</text> </svg>;

await sharp(inputPath) .composite([{ input: Buffer.from(svg), gravity: 'southeast' }]) .toFile(outputPath); }

Batch Processing with Progress

import PQueue from 'p-queue';

async function batchProcessImages( inputPaths: string[], outputDir: string, transform: (image: sharp.Sharp) => sharp.Sharp, onProgress?: (completed: number, total: number) => void ): Promise<Map<string, { success: boolean; error?: string }>> { const queue = new PQueue({ concurrency: 4 }); const results = new Map<string, { success: boolean; error?: string }>(); let completed = 0;

for (const inputPath of inputPaths) { queue.add(async () => { const filename = path.basename(inputPath, path.extname(inputPath)) + '.webp'; try { let image = sharp(inputPath); image = transform(image); await image.toFile(path.join(outputDir, filename)); results.set(inputPath, { success: true }); } catch (error) { results.set(inputPath, { success: false, error: error.message }); } completed++; onProgress?.(completed, inputPaths.length); }); }

await queue.onIdle(); return results; }

Best Practices

Do Avoid

Use WebP/AVIF for modern browsers with JPEG fallback Serving only JPEG/PNG to all browsers

Generate LQIP placeholders for lazy loading Loading full images without placeholders

Cache processed images to avoid reprocessing Re-processing the same image on each request

Use withoutEnlargement to prevent upscaling Scaling images larger than their original size

Strip EXIF metadata for privacy and smaller files Exposing GPS and camera data in public images

Validate image dimensions and format before processing Processing arbitrary files without validation

Use streams for large images to reduce memory Loading very large images entirely into memory

Set appropriate quality (70-85) for web delivery Over-compressing (below 60) or under-compressing

Use sharp.strategy.attention for thumbnails Using center crop for all images

Provide fallback formats for older browsers Assuming all browsers support WebP/AVIF

Related Skills

• media-processing - Video and audio processing

• frontend-design - Image usage in UI design

References

• Sharp Documentation

• Web.dev Image Optimization

• Squoosh - Format comparison tool

• Can I Use AVIF