@optivor/js

Official JavaScript & TypeScript SDK for Optivor image optimization engine.

⭐ If you find Optivor useful, please consider giving us a Star on GitHub!

@optivor/js is a lightweight, zero-dependency client library for constructing Optivor image transformation URLs, handling signed URL generation, and managing multi-bucket image routing.

Installation

npm install @optivor/js
# or
pnpm add @optivor/js
# or
yarn add @optivor/js

Basic Usage

import { OptivorClient } from '@optivor/js';

const optivor = new OptivorClient({
  baseUrl: 'https://optivor.example.com',
  defaultBucket: 's3-bucket'
});

// Generate optimized WebP URL
const imageUrl = optivor.buildUrl('users/avatar.jpg', {
  width: 300,
  height: 300,
  fit: 'cover',
  format: 'webp'
});
// => https://optivor.example.com/image/s3-bucket/users/avatar.jpg?w=300&h=300&fit=cover&format=webp

Preset-Based Image Optimization (Recommended)

Optivor encourages server-configured presets (e.g. avatar, profile, hero, thumbnail) to maintain consistent dimensions and security policies across your application.

// Build URL using a server-side preset
const presetUrl = optivor.buildPresetUrl('avatar', 'users/john.jpg');
// => https://optivor.example.com/preset/avatar/s3-bucket/users/john.jpg

// Build preset URL with optional overrides
const customPresetUrl = optivor.buildUrl('users/john.jpg', {
  preset: 'profile',
  format: 'avif'
});
// => https://optivor.example.com/preset/profile/s3-bucket/users/john.jpg?format=avif

Advanced Transformation Options

@optivor/js supports all Optivor V1.2 transformation parameters:

const bannerUrl = optivor.buildUrl('banners/hero.png', {
  width: 1200,
  height: 600,
  fit: 'focal',
  focal: [0.3, 0.7],          // Focal point X: 30%, Y: 70%
  format: 'avif',
  overlay: 'watermark.png',   // Filigran / logo overlay key
  gravity: 'bottom_right',    // Overlay position
  opacity: 50,                // Transparency (0-100%)
  blur: 10,                   // Gaussian blur radius
  grayscale: true,            // B&W conversion
  pixelate: 5                 // Block pixelation
});

Watermark Security & Tamper Protection

To prevent end-users from stripping overlay= or watermark query parameters from public URLs:

1. HMAC URL Signing (securityKey): Enable securityKey when instantiating OptivorClient. HMAC signatures lock the full URL path and query string. Any modification or stripping of the overlay parameter invalidates the HMAC token, returning 403 Forbidden.
2. Server-Side Presets (buildPresetUrl): Use optivor.buildPresetUrl('watermarked_thumb', key) to process images using server-side presets defined in optivor.yaml. The overlay rule stays on the server, leaving no parameters for users to tamper with.

Options & Parameters Reference

OptivorClientOptions

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | baseUrl | string | 'http://localhost:8080' | Base URL of your Optivor server. | | defaultBucket | string | '' | Optional default storage bucket alias. |

TransformParams

| Parameter | Type | Description | | :--- | :--- | :--- | | width / w | number | Target image width in pixels. | | height / h | number | Target image height in pixels. | | fit | 'cover' \| 'contain' \| 'fill' \| 'smart' \| 'focal' | Resizing & cropping strategy. | | format | 'webp' \| 'avif' \| 'gif' \| 'mp4' | Output image format. | | focal | [number, number] | Normalized focal point coordinates [x, y] (0.0 to 1.0). | | overlay | string | Overlay image key / logo path. | | gravity | string | Position: center, north_west, bottom_right, etc. | | opacity | number | Overlay transparency (0 to 100). | | blur | number | Gaussian blur radius. | | grayscale | boolean | Convert image to monochrome. | | pixelate | number | Downscale/upscale block size for pixel art. |

License

Apache-2.0 © Optivor Team