Image Transformations

The SDK provides utilities for transforming images using Cloudflare's Image Resizing service. Images are resized on-the-fly without pre-generating thumbnails.

Overview

• No pre-generated thumbnails needed
• Automatic format optimization (WebP/AVIF when browser supports it)
• Responsive images with srcset generation
• Works with any media stored in PerspectAPI

Basic Usage

import { buildImageUrl } from 'perspectapi-ts-sdk';

// Generate a resized image URL
const url = buildImageUrl('https://api.example.com', '/media/photo.jpg', {
  width: 800,
  quality: 85,
  format: 'auto'
});

// Result: https://api.example.com/cdn-cgi/image/width=800,quality=85,format=auto/media/photo.jpg

Responsive Images

import { generateSrcSet, generateSizesAttribute } from 'perspectapi-ts-sdk';

const sizes = [
  { width: 400, media: '(max-width: 640px)' },
  { width: 800, media: '(max-width: 1024px)' },
  { width: 1200 }
];

const srcset = generateSrcSet('https://api.example.com', '/media/hero.jpg', sizes);
const sizesAttr = generateSizesAttribute(sizes);

// Use in HTML/JSX:
// <img srcset={srcset} sizes={sizesAttr} alt="Hero" />

Transform Options

interface ImageTransformOptions {
  width?: number;            // Target width in pixels
  height?: number;           // Target height in pixels
  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
  gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center';
  quality?: number;          // 1-100
  format?: 'auto' | 'avif' | 'webp' | 'jpeg' | 'png';
  sharpen?: number;
  blur?: number;
  rotate?: number;
  dpr?: number;              // Device pixel ratio
  metadata?: 'keep' | 'copyright' | 'none';
  background?: string;       // CSS color for padding
}

Default Size Presets

import { DEFAULT_IMAGE_SIZES } from 'perspectapi-ts-sdk';

// Available presets:
// thumbnail: 150x150, cover, quality 85
// small:     400w, scale-down, quality 85
// medium:    800w, scale-down, quality 85
// large:     1200w, scale-down, quality 85
// original:  format auto only

React Component Example

import { generateSrcSet, generateSizesAttribute } from 'perspectapi-ts-sdk';

function ResponsiveImage({ src, alt }: { src: string; alt: string }) {
  const baseUrl = import.meta.env.VITE_API_URL;
  const sizes = [
    { width: 400, media: '(max-width: 640px)' },
    { width: 800, media: '(max-width: 1024px)' },
    { width: 1200 }
  ];

  return (
    <img
      src={`${baseUrl}/cdn-cgi/image/width=800,format=auto${src}`}
      srcSet={generateSrcSet(baseUrl, src, sizes)}
      sizes={generateSizesAttribute(sizes)}
      alt={alt}
      loading="lazy"
    />
  );
}