Visionary-url NPM

Visionary URL is a lightweight Typescript library for generating image URLs with built-in Blurhash placeholders.

NPM version GitHub Actions Workflow Status NPM bundle size

Getting started

Install visionary-url via npm. Both ES modules and CommonJS modules are supported.

npm install --save visionary-url

Generating a Visionary URL

import { generateVisionaryUrl } from 'visionary-url';

const url = generateVisionaryUrl({
  blurhash: "LCDJYN9FxG_M_N%L%M%M4o~ptRIA", // blurhash string
  blurhashX: 4, // blurhash x components
  blurhashY: 4, // blurhash y components
  bcc: "#baccae", // background color code
  fileId: "image:101", // image ID or URL
  sourceHeight: 1200, // image height
  sourceWidth: 1600, // image width
});

How it works

A Visionary URL is formatted using 3 or 4 URL segments: | | base path | | visionary code | | options (optional) | | filename | | -- | -- | -- | -- | -- | -- | -- | -- | | / | image | / | <visionary code, base64url> | / |<option tokens> | / | image.jpg |

Example URLs

https://examplecdn.cloud/image/aW1hZ2U6MTAwMDEhODAwITYwMA/image.jpg
https://examplecdn.cloud/image/aW1hZ2U6MTAwMDEhODAwITYwMA/4k/image.jpg

Visionary code

The Visionary code is a base64url'd, exclamation-point separated list of image placeholder data, detailed as the following:

Attribute	Description
Image ID	Image URL or internal image ID (required)
Image width	Used to compute aspect ratio of image placeholder (required)
Image height	Used to compute aspect ratio of image placeholder (required)
Background color code	Base layer background color code (e.g. `#BACCAE`)
Blurhash code	Blurhash string of the image
Blurhash x components	Number of x components the blurhash code represents
Blurhash y components	Number of y components the blurhash code represents