Image processing utilities for resizing, cropping, format conversion, and optimization with social media aspect ratios
npm install @bernierllc/image-processorImage processing utilities for resizing, cropping, format conversion, and optimization with built-in support for social media aspect ratios.
``bash`
npm install @bernierllc/image-processor
- Image Transformations: Resize, crop, and optimize images
- Format Conversion: Convert between JPEG, PNG, WebP, and AVIF
- Social Media Presets: Built-in aspect ratios for Instagram, Twitter, Facebook, LinkedIn, and YouTube
- Thumbnail Generation: Create square thumbnails from any image
- Quality Optimization: Reduce file size while maintaining visual quality
- Metadata Extraction: Retrieve image dimensions, format, and properties
- Logger Integration: Built-in logging with @bernierllc/logger
- Type-Safe: Full TypeScript support with strict typing
`typescript
import { ImageProcessor } from '@bernierllc/image-processor';
import fs from 'fs';
const processor = new ImageProcessor();
// Read an image
const imageBuffer = fs.readFileSync('photo.jpg');
// Resize image
const resized = await processor.resize(imageBuffer, {
width: 800,
height: 600
});
if (resized.success) {
fs.writeFileSync('photo-resized.jpg', resized.data!);
console.log('Dimensions:', resized.metadata);
}
`
`typescript
// Resize to specific dimensions
const result = await processor.resize(imageBuffer, {
width: 1200,
height: 800
});
// Resize by width only (maintains aspect ratio)
const widthOnly = await processor.resize(imageBuffer, {
width: 1000
});
// Resize by height only (maintains aspect ratio)
const heightOnly = await processor.resize(imageBuffer, {
height: 600
});
// Resize with fit option
const covered = await processor.resize(imageBuffer, {
width: 800,
height: 800,
fit: 'cover' // Options: cover, contain, fill, inside, outside
});
`
`typescript
// Crop to specific dimensions
const cropped = await processor.crop(imageBuffer, {
width: 1080,
height: 1080,
position: 'center' // center, top, bottom, left, right, top-left, etc.
});
// Crop from different positions
const topCrop = await processor.crop(imageBuffer, {
width: 500,
height: 500,
position: 'top'
});
`
`typescript
// Instagram square (1:1 - 1080x1080)
const instagramSquare = await processor.cropForSocialMedia(
imageBuffer,
'instagram-square'
);
// Instagram portrait (4:5 - 1080x1350)
const instagramPortrait = await processor.cropForSocialMedia(
imageBuffer,
'instagram-portrait'
);
// Instagram story (9:16 - 1080x1920)
const instagramStory = await processor.cropForSocialMedia(
imageBuffer,
'instagram-story'
);
// Twitter post (16:9 - 1200x675)
const twitterPost = await processor.cropForSocialMedia(
imageBuffer,
'twitter-post'
);
// Facebook cover (2.7:1 - 820x312)
const facebookCover = await processor.cropForSocialMedia(
imageBuffer,
'facebook-cover'
);
// YouTube thumbnail (16:9 - 1280x720)
const youtubeThumbnail = await processor.cropForSocialMedia(
imageBuffer,
'youtube-thumbnail'
);
`
`typescript
// Convert to WebP
const webp = await processor.toFormat(imageBuffer, {
format: 'webp',
quality: 85
});
// Convert to PNG
const png = await processor.toFormat(imageBuffer, {
format: 'png',
quality: 90
});
// Convert with metadata stripping
const jpeg = await processor.toFormat(imageBuffer, {
format: 'jpeg',
quality: 80,
stripMetadata: true
});
// Convert to AVIF (modern format with excellent compression)
const avif = await processor.toFormat(imageBuffer, {
format: 'avif',
quality: 75
});
`
`typescript
// Optimize with quality reduction
const optimized = await processor.optimize(imageBuffer, {
quality: 75
});
// Optimize with format conversion
const optimizedWebP = await processor.optimize(imageBuffer, {
quality: 80,
format: 'webp'
});
// Optimize and keep metadata
const optimizedWithMetadata = await processor.optimize(imageBuffer, {
quality: 85,
stripMetadata: false
});
`
`typescript
// Generate 200x200 square thumbnail
const thumbnail = await processor.thumbnail(imageBuffer, 200);
// Generate smaller thumbnail
const smallThumb = await processor.thumbnail(imageBuffer, 100);
`
`typescript
const metadata = await processor.getMetadata(imageBuffer);
if (metadata.success) {
console.log('Width:', metadata.metadata?.width);
console.log('Height:', metadata.metadata?.height);
console.log('Format:', metadata.metadata?.format);
console.log('File size:', metadata.metadata?.size, 'bytes');
console.log('Has alpha:', metadata.metadata?.hasAlpha);
}
`
`typescript
import {
getSocialMediaDimensions,
isValidPreset,
SOCIAL_MEDIA_PRESETS
} from '@bernierllc/image-processor';
// Get dimensions for a preset
const dimensions = getSocialMediaDimensions('instagram-square');
console.log(dimensions); // { width: 1080, height: 1080, aspectRatio: '1:1' }
// Check if preset is valid
if (isValidPreset('twitter-post')) {
const dims = getSocialMediaDimensions('twitter-post');
console.log('Valid preset:', dims);
}
// Access all presets
console.log(SOCIAL_MEDIA_PRESETS);
`
All methods return a ProcessResult object with error handling:
`typescript
const result = await processor.resize(imageBuffer, {
width: 800,
height: 600
});
if (result.success) {
console.log('Success!');
console.log('Data:', result.data);
console.log('Metadata:', result.metadata);
} else {
console.error('Error:', result.error);
}
`
Main class for image processing operations.
#### Methods
##### resize(input: Buffer, options: ResizeOptions): Promise
Resize an image to specified dimensions.
Options:
- width?: number - Target width in pixelsheight?: number
- - Target height in pixelsfit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
- - How to fit image (default: 'inside')withoutEnlargement?: boolean
- - Prevent enlarging small images (default: false)
##### crop(input: Buffer, options: CropOptions): Promise
Crop an image to specific dimensions.
Options:
- width: number - Target width in pixelsheight: number
- - Target height in pixelsposition?: CropPosition
- - Position to crop from (default: 'center')
##### cropForSocialMedia(input: Buffer, preset: SocialMediaAspectRatio): Promise
Crop an image for a social media platform using preset dimensions.
Presets:
- instagram-square (1:1 - 1080x1080)instagram-portrait
- (4:5 - 1080x1350)instagram-landscape
- (1.91:1 - 1080x566)instagram-story
- (9:16 - 1080x1920)twitter-post
- (16:9 - 1200x675)twitter-header
- (3:1 - 1500x500)facebook-post
- (1.91:1 - 1200x628)facebook-cover
- (2.7:1 - 820x312)linkedin-post
- (1.91:1 - 1200x627)youtube-thumbnail
- (16:9 - 1280x720)
##### toFormat(input: Buffer, options: FormatOptions): Promise
Convert an image to a different format.
Options:
- format: ImageFormat - Output format ('jpeg', 'png', 'webp', 'avif')quality?: number
- - Quality setting (1-100, format dependent)stripMetadata?: boolean
- - Whether to strip metadata (default: false)
##### optimize(input: Buffer, options: OptimizeOptions): Promise
Optimize an image by reducing quality and/or file size.
Options:
- quality: number - Quality setting (1-100)stripMetadata?: boolean
- - Whether to strip metadata (default: true)format?: ImageFormat
- - Target format (default: original format)
##### thumbnail(input: Buffer, size: number): Promise
Generate a square thumbnail from an image.
Parameters:
- size: number - Thumbnail size in pixels (creates size x size image)
##### getMetadata(input: Buffer): Promise
Get metadata information from an image.
Returns metadata including:
- width: number - Image width in pixelsheight: number
- - Image height in pixelsformat: string
- - Image formatsize: number
- - File size in bytesspace?: string
- - Color spacechannels?: number
- - Number of channelsdensity?: number
- - Pixel densityhasAlpha?: boolean
- - Whether image has alpha channel
`typescript
type ImageFormat = 'jpeg' | 'png' | 'webp' | 'avif';
type CropPosition =
| 'center'
| 'top'
| 'bottom'
| 'left'
| 'right'
| 'top-left'
| 'top-right'
| 'bottom-left'
| 'bottom-right';
type SocialMediaAspectRatio =
| 'instagram-square'
| 'instagram-portrait'
| 'instagram-landscape'
| 'instagram-story'
| 'twitter-post'
| 'twitter-header'
| 'facebook-post'
| 'facebook-cover'
| 'linkedin-post'
| 'youtube-thumbnail';
interface ProcessResult {
success: boolean;
data?: Buffer;
metadata?: ImageMetadata;
error?: string;
}
interface ImageMetadata {
width: number;
height: number;
format: string;
size: number;
space?: string;
channels?: number;
density?: number;
hasAlpha?: boolean;
}
`
- @bernierllc/logger - Logging integration
- sharp - High-performance image processing library
Justification: This package uses @bernierllc/logger for operation logging. Image processing operations (resize, crop, convert) are logged with metadata including dimensions, formats, and processing times. This helps with debugging, performance monitoring, and tracking image processing workflows.
Pattern: Direct integration - logger is a required dependency for this package.
Justification: This is a core utility package that performs image processing operations. It does not participate in service discovery, event publishing, or service mesh operations. Image processing is a stateless utility operation that doesn't require service registration or discovery.
Pattern: Core utility - no service mesh integration needed.
Format: TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.
This package has comprehensive test coverage (90%+) including:
- Resize operations with various options
- Crop operations with different positions
- Social media aspect ratio cropping
- Format conversions
- Image optimization
- Thumbnail generation
- Metadata extraction
- Edge cases and error handling
`bash`
npm test # Run tests in watch mode
npm run test:run # Run tests once
npm run test:coverage # Generate coverage report
`typescript
async function processUserAvatar(uploadBuffer: Buffer) {
const processor = new ImageProcessor();
// Generate multiple sizes
const large = await processor.thumbnail(uploadBuffer, 512);
const medium = await processor.thumbnail(uploadBuffer, 256);
const small = await processor.thumbnail(uploadBuffer, 128);
// Optimize for web
const optimized = await processor.optimize(uploadBuffer, {
quality: 85,
format: 'webp'
});
return {
large: large.data,
medium: medium.data,
small: small.data,
optimized: optimized.data
};
}
`
`typescript
async function createSocialMediaAssets(imageBuffer: Buffer) {
const processor = new ImageProcessor();
const assets = {
instagram: await processor.cropForSocialMedia(imageBuffer, 'instagram-square'),
twitter: await processor.cropForSocialMedia(imageBuffer, 'twitter-post'),
facebook: await processor.cropForSocialMedia(imageBuffer, 'facebook-post'),
youtube: await processor.cropForSocialMedia(imageBuffer, 'youtube-thumbnail')
};
// Convert all to WebP for optimal file size
for (const [platform, result] of Object.entries(assets)) {
if (result.success && result.data) {
const webp = await processor.toFormat(result.data, {
format: 'webp',
quality: 85
});
assets[platform] = webp;
}
}
return assets;
}
`
`typescript
async function optimizeImageDirectory(inputDir: string, outputDir: string) {
const processor = new ImageProcessor();
const files = fs.readdirSync(inputDir);
for (const file of files) {
if (!file.match(/\.(jpg|jpeg|png)$/i)) continue;
const inputPath = path.join(inputDir, file);
const outputPath = path.join(outputDir, file.replace(/\.\w+$/, '.webp'));
const buffer = fs.readFileSync(inputPath);
const optimized = await processor.optimize(buffer, {
quality: 80,
format: 'webp'
});
if (optimized.success) {
fs.writeFileSync(outputPath, optimized.data!);
console.log(Optimized: ${file} -> ${path.basename(outputPath)});`
}
}
}
The package uses the sharp` library, which provides:
- High-performance image processing
- Low memory usage
- Support for large images
- Hardware acceleration where available
Copyright (c) 2025 Bernier LLC. All rights reserved.
- @bernierllc/logger - Logging utilities
- @bernierllc/media-manager - Media asset management (Wave 3)
- @bernierllc/social-media-instagram - Instagram integration (Wave 3)