Hikaru SDK

Fast, privacy-first client-side image optimization for modern web apps.

Compress images before they leave the user's device. Save server bandwidth, cut storage costs, and protect user privacy instantly.

Features

• 100% Client-Side: Processing happens entirely in the browser. No servers required.
• Auto EXIF Stripping: Automatically removes GPS coords, device models, and camera data.
• Hardware Accelerated: Uses OffscreenCanvas and createImageBitmap off the main UI thread.
• Tiny Footprint: Zero dependencies. Extremely lightweight.

Installation

npm install @cfbl/hikaru-sdk

Usage

The API is designed for simplicity and power.

1. Default Configuration

Automatically scales down photos to a web-safe size (max 1920px) at 80% quality.

import { compress } from "@cfbl/hikaru-sdk";

const optimized = await compress(file);

2. Presets

Pass a preset string to standardize user uploads. Available presets: avatar, thumbnail, feed, hero.

import { compress } from "@cfbl/hikaru-sdk";

const avatar = await compress(file, "avatar"); 

3. Batch Processing

Pass an array of files. Process sequentially to prevent browser memory crashes, complete with a progress hook.

import { compress } from "@cfbl/hikaru-sdk";

const results = await compress(
  [file1, file2, file3], 
  "feed", 
  (completed, total, currentFile) => {
    console.log(`Processed ${completed}/${total}: ${currentFile.name}`);
  }
);

4. Custom Configuration

Pass an options object for exact control over dimensions, quality, and format.

import { compress } from "@cfbl/hikaru-sdk";

const custom = await compress(file, {
  width: 800,           // Auto-calculates proportional height
  quality: 0.75,        // 75% quality
  format: "webp",       // Convert to WebP
  keepOriginalIfSmaller: true // Safety guard
});

API Reference

interface CompressOptions {
  preset?: "auto" | "avatar" | "thumbnail" | "feed" | "hero";
  quality?: number;      // 0.1 to 1.0
  width?: number;        // Exact width in px
  height?: number;       // Exact height in px
  maxWidth?: number;     // Scale down if width exceeds this
  maxHeight?: number;    // Scale down if height exceeds this
  format?: "jpeg" | "jpg" | "webp" | "png";
  keepOriginalIfSmaller?: boolean; // Default: true
}