@spronta/images

Core URL builder, signing, and blurhash utilities for the Spronta image CDN.

Zero dependencies. Works in Node.js, browsers, Deno, Bun, and Cloudflare Workers.

Install

npm install @spronta/images

Quick start

import { Spronta } from "@spronta/images";

const spronta = new Spronta({
  baseUrl: "https://cdn.spronta.com",
  project: "my-project",
});

// Generate a URL
const url = spronta.url("hero.jpg", { width: 800, format: "auto", quality: "medium" });
// → https://cdn.spronta.com/my-project/hero.jpg?w=800&f=auto&q=medium

// Generate responsive srcset
const { src, srcset, sizes } = spronta.srcset("photo.jpg", {
  widths: [400, 800, 1200],
  sizes: "(max-width: 768px) 100vw, 50vw",
});

Signed URLs

const spronta = new Spronta({
  baseUrl: "https://cdn.spronta.com",
  project: "my-project",
  signingSecret: "spronta_sign_...",
});

const url = await spronta.signedUrl("private.jpg", {
  width: 800,
  expiresIn: 3600, // 1 hour
});

Blurhash

import { decodeBlurhash, blurhashToCssUrl, blurhashToColor } from "@spronta/images";

// Decode to RGBA pixels
const pixels = decodeBlurhash("LEHV6nWB2y", 32, 32);

// Get a CSS background (canvas data URL in browser, solid color in SSR)
const cssUrl = blurhashToCssUrl("LEHV6nWB2y", 32, 32);

// Extract average color
const hex = blurhashToColor("LEHV6nWB2y"); // → "#a4c3b2"

Transform options

Option	Type	Description
width	number	Output width (1–8192)
height	number	Output height (1–8192)
fit	string	cover, contain, fill, scale-down, crop, pad
format	string	auto, jpeg, png, webp, avif, jxl
quality	number | string	1–100 or high, medium, low
gravity	string	auto, face, center, position keywords
blur	number	Gaussian blur (1–250)
sharpen	number	Unsharp mask (0–10)
radius	number | "max"	Corner radius
rotate	number	90, 180, 270
flip	string	h, v
preset	string	Named transform preset

See full parameter reference for all options.

Framework integrations

• React: @spronta/images-react
• Next.js: @spronta/images-next

License

MIT