@pixelfiddler/core

Core utilities for building PixelFiddler image transformation URLs.

Installation

npm install @pixelfiddler/core
# or
pnpm add @pixelfiddler/core
# or
yarn add @pixelfiddler/core

Usage

import { buildTransformationUrl, buildTransformationQueryParams } from '@pixelfiddler/core';

// Build a complete transformation URL
const url = buildTransformationUrl({
  src: '/images/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: {
    width: 800,
    height: 600,
    format: 'WEBP',
    quality: 85,
  }
});
// => 'https://cdn.example.com/images/photo.jpg?w=800&h=600&f=WEBP&q=85'

// Or just get the query string
const params = buildTransformationQueryParams({
  width: 400,
  blur: 5,
  grayscale: true,
});
// => 'w=400&bl=5&gs=true'

API

buildTransformationUrl(config)

Builds a complete transformation URL.

buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: { width: 800, format: 'WEBP' },
  mode: 'short' // optional, default: 'short'
});

| Parameter | Type | Description | |-----------|------|-------------| | src | string | Relative or absolute path to the image | | baseUrl | string | Base URL endpoint from PixelFiddler Dashboard | | transformations | TransformationOptions | Transformation options | | mode | 'short' \| 'long' | Parameter naming mode (default: 'short') |

buildTransformationQueryParams(options, mode?)

Converts transformation options to a URL-encoded query string.

buildTransformationQueryParams({ width: 800, format: 'WEBP' });
// => 'w=800&f=WEBP'

buildTransformationQueryParams({ width: 800 }, 'long');
// => 'width=800'

| Parameter | Type | Description | |-----------|------|-------------| | options | TransformationOptions | Transformation options | | mode | 'short' \| 'long' | Parameter naming mode (default: 'short') |

createResponsiveAttributes(src, baseUrl?, options?)

Generates responsive image attributes (src, srcSet, sizes) for optimal loading.

import { createResponsiveAttributes } from '@pixelfiddler/core';

// Responsive image with sizes (uses `w` descriptors)
createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
  sizes: '(max-width: 768px) 100vw, 50vw',
  transformations: { format: 'WEBP' }
});
// => {
//   src: '...?w=3840&f=WEBP',
//   srcSet: '...?w=640&f=WEBP 640w, ...?w=1024&f=WEBP 1024w, ...',
//   sizes: '(max-width: 768px) 100vw, 50vw'
// }

// Fixed-width image (uses `x` descriptors for DPR)
createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
  width: 400
});
// => {
//   src: '...?w=384',
//   srcSet: '...?w=384 1x, ...?w=828 2x',
//   width: 400
// }

| Parameter | Type | Description | |-----------|------|-------------| | src | string | Relative or absolute path to the image | | baseUrl | string | Base URL endpoint from PixelFiddler Dashboard | | options.sizes | string | Sizes attribute for responsive layouts | | options.width | number | Fixed display width (generates DPR variants) | | options.deviceBreakpoints | number[] | Custom device breakpoints | | options.imageBreakpoints | number[] | Custom image breakpoints | | options.transformations | TransformationOptions | Base transformations to apply | | options.maxDpr | number | Maximum DPR to support (default: 2) |

Transformation Options

Resize

{
  width: 800,           // Target width (px)
  height: 600,          // Target height (px)
  dpr: 2,               // Device pixel ratio (1-4)
  mode: 'FIT',          // 'FILL' | 'FIT' | 'PAD'
  background: '#ffffff' // Background color for PAD mode
}

Format & Quality

{
  format: 'WEBP',       // 'JPG' | 'PNG' | 'WEBP' | 'AVIF' | 'GIF'
  quality: 80,          // 1-100
  stripMetadata: true   // Remove EXIF data
}

Effects

{
  blur: 5,              // Gaussian blur (0-100)
  brightness: 10,       // Brightness adjustment (0-100)
  contrast: 20,         // Contrast adjustment (0-100)
  saturation: 30,       // Saturation adjustment (0-100)
  sharpen: 15,          // Sharpen intensity (0-100)
  noise: 5,             // Add noise (0-100)
  grayscale: true,      // Convert to grayscale
  sepia: true,          // Apply sepia effect
  rotate: 90            // Rotation (0 | 90 | 180 | 270)
}

Border

{
  border: {
    width: 2,           // Border width (px)
    color: '#000000',   // Border color
    radius: 8           // Corner radius (px, 1-2000)
  }
}

Crop

// Simple crop with auto focus
{
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'AUTO',
      strategy: 'SMART'     // 'CENTER' | 'SMART' | 'DETAIL'
    },
    afterResize: true
  }
}

// Simple crop with specified position
{
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'SPECIFIED',
      position: { x: 50, y: 50 }
    }
  }
}

// Object detection crop
{
  crop: {
    type: 'OBJECT',
    objectType: 'FACE',     // 'FACE' | 'UPPER_BODY'
    width: 400,
    height: 300
  }
}

Text Overlay

{
  text: {
    text: 'Hello World',
    color: '#ffffff',
    opacity: 80,            // 0-100
    size: 50,               // Size as percentage (1-100)
    font: 'Arial',
    fontSize: 24,           // Font size in pixels
    position: 'CENTER',     // Position constant
    background: '#000000',
    backgroundOpacity: 50
  }
}

Watermark

{
  watermark: {
    name: 'logo',           // Predefined watermark name
    opacity: 50,
    size: 25,               // Size as percentage
    width: 100,             // Or explicit dimensions
    height: 50,
    position: 'BOTTOM_RIGHT'
  }
}

Position Values

For text.position and watermark.position:

'TOP_LEFT' | 'TOP' | 'TOP_RIGHT' |
'LEFT' | 'CENTER' | 'RIGHT' |
'BOTTOM_LEFT' | 'BOTTOM' | 'BOTTOM_RIGHT' |
'AUTO'

Special Options

{
  original: true,   // Return original image (no transformations)
  alias: 'thumb'    // Use predefined transformation alias
}

Parameter Aliases

By default, short parameter names are used for smaller URLs:

| Option | Short | Long | |--------|-------|------| | width | w | width | | height | h | height | | format | f | format | | quality | q | quality | | blur | bl | blur | | ... | ... | ... |

Use mode: 'long' for full parameter names:

buildTransformationQueryParams({ width: 800 }, 'long');
// => 'width=800'

TypeScript

Full TypeScript support with exported types:

import type {
  // Main options
  TransformationOptions,
  PixelFiddlerConfig,
  UrlBuilderConfig,
  BuildTransformationConfig,

  // Resize
  ResizeOptions,
  ResizeMode,
  DevicePixelRatio,

  // Format
  FormatOptions,
  ImageFormat,

  // Effects
  EffectOptions,
  RotationAngle,

  // Border
  BorderOptions,
  HexColor,

  // Crop
  CropOptions,
  SimpleCropOptions,
  ObjectCropOptions,
  CropFocusOptions,
  CropType,
  CropFocus,
  CropFocusStrategy,
  CropObjectType,

  // Overlays
  TextOptions,
  WatermarkOptions,
  Position,
} from '@pixelfiddler/core';

License

MIT