Sharpify NPM | npm.io

Sharpify

A powerful TypeScript library for image processing built on top of Sharp. Sharpify provides an intuitive interface for common image manipulation tasks with built-in caching and error handling.

Demo

Try out Sharpify in your browser: Sharpify Demo

Repository

Find the source code and documentation on GitHub:

https://github.com/yassinemontassar/Sharpify

Requirements

Node.js >= 18
TypeScript >= 5.3
Sharp >= 0.33

Features

🖼️ Comprehensive image processing capabilities
🚀 Built-in image caching for improved performance
🎨 Advanced color manipulation and effects
💧 Watermark support with customizable positioning and fonts
📏 Flexible resizing and cropping options
🎯 Batch processing support
💪 Strong TypeScript support
🐛 Robust error handling

Installation

npm install sharpify
# or
yarn add sharpify
# or
pnpm add sharpify

Quick Start

import { Sharpify } from 'sharpify';
import { readFileSync } from 'fs';

// Read an image
const imageBuffer = readFileSync('input.jpg');

// Process the image
const processed = await Sharpify.process(imageBuffer, {
  width: 800,
  height: 600,
  format: 'webp',
  quality: 80,
  grayscale: true
});

// Access the processed image data
console.log(processed.metadata);

Type Definitions

Sharpify comes with comprehensive TypeScript definitions. You can import the types directly:

import type {
  ImageStats,
  WatermarkPosition,
  WatermarkFont,
  ImageProcessorOptions,
  ProcessedImage
} from 'sharpify';

// Example usage with types
const options: ImageProcessorOptions = {
  width: 800,
  height: 600,
  format: 'webp',
  watermark: {
    text: '© 2024',
    position: 'bottom-right'
  }
};

// The processed result will be strongly typed
const result: ProcessedImage = await Sharpify.process(imageBuffer, options);

Available Types

ImageStats: Metadata and details about an image
WatermarkPosition: Position options for watermarks ('top-left', 'center', etc.)
WatermarkFont: Available font options for watermark text
ImageProcessorOptions: Complete configuration options for image processing
ProcessedImage: Structure of the processed image result
CacheEntry: Internal cache storage structure

API Reference

Sharpify.process(input: Buffer, options?: ImageProcessorOptions): Promise

Process a single image with various options.

Options

{
  format?: 'jpeg' | 'png' | 'webp' | 'avif';
  quality?: number;                    // 1-100
  width?: number;                      // output width
  height?: number;                    // output height
  crop?: {                            // crop coordinates
    left: number;
    top: number;
    width: number;
    height: number;
  };
  blur?: number;                       // blur radius
  sharpen?: boolean;                   // apply sharpening
  grayscale?: boolean;                 // convert to grayscale
  rotate?: number;                     // rotation angle
  flip?: boolean;                      // vertical flip
  flop?: boolean;                      // horizontal flip
  tint?: string;                       // color tint
  brightness?: number;                 // adjust brightness
  saturation?: number;                 // adjust saturation
  contrast?: number;                   // adjust contrast
  watermark?: {
    text: string;                      // watermark text
    font?: WatermarkFont;              // font family
    size?: number;                     // font size
    color?: string;                    // text color
    opacity?: number;                  // 0-1
    position?: WatermarkPosition;      // positioning
  };
  aspectRatio?: number;                // custom aspect ratio for cropping
}

Return Value (ProcessedImage)

{
  data: Buffer;              // processed image buffer
  format: string;            // output format
  width: number;            // output width
  height: number;           // output height
  size: number;            // file size in bytes
  metadata: {
    hasAlpha: boolean;     // alpha channel presence
    isAnimated: boolean;   // animation status
    pages?: number;        // number of pages/frames
    compression?: string;  // compression type
    colorSpace?: string;   // color space
  };
}

Sharpify.getStats(input: Buffer): Promise

Get detailed statistics about an image.

const stats = await Sharpify.getStats(imageBuffer);
console.log(stats);
// {
//   size: number,
//   format: string,
//   width: number,
//   height: number,
//   aspectRatio: number,
//   hasAlpha: boolean,
//   colorSpace: string,
//   channels: number,
//   compression?: string
// }

Sharpify.getDominantColor(input: Buffer): Promise

Extract the dominant color from an image.

const color = await Sharpify.getDominantColor(imageBuffer);
console.log(color); // Returns RGB format, e.g., "rgb(123, 45, 67)"

Sharpify.batchProcess(inputs: Buffer[], options?: ImageProcessorOptions): Promise<ProcessedImage[]>

Process multiple images in parallel with the same options.

const images = [buffer1, buffer2, buffer3];
const processed = await Sharpify.batchProcess(images, {
  format: 'webp',
  quality: 80
});

Sharpify.createAvatar(input: Buffer, options?: AvatarOptions): Promise

Create an avatar from an image with specified options.

Options

{
  size?: number;  // Desired size of the avatar in pixels
}

Return Value (ProcessedImage)

{
  data: Buffer;              // processed avatar buffer
  format: string;            // output format
  width: number;            // output width
  height: number;           // output height
  size: number;            // file size in bytes
  metadata: {
    hasAlpha: boolean;     // alpha channel presence
    isAnimated: boolean;   // animation status
    pages?: number;        // number of pages/frames
    compression?: string;  // compression type
    colorSpace?: string;   // color space
  };
}

Examples

Basic Image Resizing

const processed = await Sharpify.process(imageBuffer, {
  width: 800,
  height: 600
});

Format Conversion with Quality Control

const processed = await Sharpify.process(imageBuffer, {
  format: 'webp',
  quality: 85
});

Adding a Watermark

const processed = await Sharpify.process(imageBuffer, {
  watermark: {
    text: '© 2024 My Company',
    position: 'bottom-right',
    size: 24,
    color: 'white',
    opacity: 0.8,
  }
});

Advanced Image Enhancement

const processed = await Sharpify.process(imageBuffer, {
  brightness: 1.2,
  contrast: 1.1,
  saturation: 1.3,
  sharpen: true
});

Creating an Avatar

const avatar = await Sharpify.createAvatar(imageBuffer, {
  size: 400
});

Error Handling

Sharpify provides detailed error information through the ImageProcessingError class:

try {
  const processed = await Sharpify.process(imageBuffer, options);
} catch (error) {
  if (error instanceof ImageProcessingError) {
    console.error(`Operation: ${error.operation}`);
    console.error(`Message: ${error.message}`);
    console.error(`Original Error: ${error.originalError}`);
  }
}

Performance Considerations

The library implements automatic caching of processed images to improve performance for repeated operations
Batch processing is performed in parallel for optimal performance
Memory usage scales with image size and number of concurrent operations