Core SDK

The Core PixelFiddler SDK provides utility functions for building image transformation URLs. It’s framework-agnostic and works in any JavaScript or TypeScript environment—Node.js, browsers, or edge runtimes.

The SDK is lightweight with full TypeScript support. You can view the source code on GitHub.

Installation and Setup

Install the Core SDK via npm, pnpm, or yarn:

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

The SDK provides utility functions for building transformation URLs. Use this package when you need full control over URL generation or are working with a framework not covered by our specialized packages.

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

const url = buildTransformationUrl({
  src: '/photos/hero.jpg',
  baseUrl: 'https://media.pixelfiddler.com/my-source',
  transformations: {
    width: 800,
    height: 600,
    format: 'WEBP',
    quality: 85,
  }
});
// => 'https://media.pixelfiddler.com/my-source/photos/hero.jpg?w=800&h=600&f=WEBP&q=85'

Utility Functions

• buildTransformationUrl – Generates a complete URL with transformation query parameters.
• buildTransformationQueryParams – Generates only the query string portion for transformations.
• createResponsiveAttributes – Generates responsive image attributes (src, srcset, sizes) for HTML img elements.

Type Definitions

The SDK provides TypeScript definitions for all functions and options, ensuring type safety and autocompletion in your IDE. Exported types include TransformationOptions, PixelFiddlerConfig, ResizeOptions, FormatOptions, EffectOptions, CropOptions, TextOptions, WatermarkOptions, BorderOptions, and more.

buildTransformationUrl

Builds a complete transformation URL with query parameters.

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

const url = buildTransformationUrl({
  src: '/photos/hero.jpg',
  baseUrl: 'https://media.pixelfiddler.com',
  transformations: {
    width: 800,
    format: 'WEBP',
    quality: 85,
  }
});
// => 'https://media.pixelfiddler.com/photos/hero.jpg?w=800&f=WEBP&q=85'

Parameter	Description
src (Required)	A relative or absolute path to the image. If a relative path is provided, it is appended to the baseUrl. If an absolute path is provided, it is used as-is. Example: /photos/hero.jpg
baseUrl	The base URL endpoint from your PixelFiddler Dashboard. Example: https://media.pixelfiddler.com
transformations	An object containing transformation options. See Transformations API for all available options.
mode	Parameter naming mode. Use 'short' (default) for abbreviated parameter names (w, h, f) or 'long' for full names (width, height, format).

Short vs Long Parameter Names

By default, the SDK uses short parameter names for smaller URLs:

// Short mode (default)
buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: { width: 800, format: 'WEBP' },
  mode: 'short'
});
// => 'https://cdn.example.com/photo.jpg?w=800&f=WEBP'

// Long mode
buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: { width: 800, format: 'WEBP' },
  mode: 'long'
});
// => 'https://cdn.example.com/photo.jpg?width=800&format=WEBP'

buildTransformationQueryParams

Builds only the query string portion without the base URL. Useful when you need to append transformations to an existing URL.

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

const params = buildTransformationQueryParams({
  width: 800,
  height: 600,
  format: 'WEBP',
  quality: 85,
});
// => 'w=800&h=600&f=WEBP&q=85'

// Use with an existing URL
const existingUrl = 'https://cdn.example.com/image.jpg';
const finalUrl = `${existingUrl}?${params}`;

Parameter	Description
options (Required)	An object containing transformation options. See Transformations API.
mode	Parameter naming mode: 'short' (default) or 'long'.

createResponsiveAttributes

Generates responsive image attributes (src, srcset, sizes, width) that can be spread onto an HTML <img> element.

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

// Fixed-width image with DPR support
const attrs = createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
  width: 400,
  transformations: { format: 'WEBP' }
});
// => {
//   src: '...?w=400&f=WEBP',
//   srcSet: '...?w=400&f=WEBP 1x, ...?w=800&f=WEBP 2x',
//   width: 400
// }

// Responsive image with sizes
const responsiveAttrs = 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'
// }

Parameter	Description
src (Required)	Relative or absolute path to the image.
baseUrl	Base URL endpoint from PixelFiddler Dashboard.
options.width	Fixed display width. Generates DPR descriptors (1x, 2x).
options.sizes	Sizes attribute for responsive layouts. Generates width descriptors (640w, 1024w).
options.deviceBreakpoints	Custom device breakpoints for responsive srcset.
options.imageBreakpoints	Custom image breakpoints for smaller images.
options.transformations	Base transformations to apply to all generated URLs. See Transformations API.
options.maxDpr	Maximum DPR to support (default: 2).

Using with HTML

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

const attrs = createResponsiveAttributes('/hero.jpg', 'https://cdn.example.com', {
  sizes: '100vw',
  transformations: { format: 'WEBP', quality: 85 }
});

// In your HTML template
const img = `<img
  src="${attrs.src}"
  srcset="${attrs.srcSet}"
  sizes="${attrs.sizes}"
  alt="Hero image"
/>`;

Applying Transformations

All functions accept a transformations object. For a complete list of available options, see the Transformations API.

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

// Resize and format
const resized = buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: {
    width: 800,
    height: 600,
    mode: 'FIT',
    format: 'WEBP',
    quality: 85,
  }
});

// Apply effects
const blurred = buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: {
    blur: 20,
    brightness: 60,
    grayscale: true,
  }
});

// Add watermark
const watermarked = buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: {
    watermark: {
      name: 'logo',
      position: 'BOTTOM_RIGHT',
      opacity: 50,
    }
  }
});

Parameter Aliases

The SDK uses short parameter names by default for smaller URLs:

Option	Short	Long
width	w	width
height	h	height
format	f	format
quality	q	quality
blur	bl	blur
brightness	br	brightness
contrast	con	contrast
saturation	sat	saturation
sharpen	sh	sharpen
grayscale	gs	grayscale
rotate	rt	rotate

Use mode: 'long' for full parameter names when needed.

TypeScript Support

The SDK provides full TypeScript support with exported types:

import type {
  TransformationOptions,
  PixelFiddlerConfig,
  BuildTransformationConfig,
  ResizeOptions,
  FormatOptions,
  EffectOptions,
  CropOptions,
  BorderOptions,
  TextOptions,
  WatermarkOptions,
} from '@pixelfiddler/core';

For all transformation types, see the Transformations API.