Refract Start building

Documentation

Quickstart & reference.

Point Refract at an image origin, request a transform by URL, and read the result off the wire. Originals are fetched on demand and edge-cached — never stored permanently.

Quickstart

Three steps to a transform.

  1. 1

    Create a key, connect an origin.

    Create an API key and point it at an existing image origin. There is no re-upload: Refract fetches originals on demand and caches the transformed variants at the edge.

    A single blank machined aluminium plate lying flat on a graphite surface under hard cool directional light.
  2. 2

    Request your first transform.

    Append parameters to the source path. The origin resizes to 1200px wide, negotiates a format from the Accept header, and returns at quality 80: 

    https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80
  3. 3

    Automate with the SDK.

    The SDK builds the same string from a typed options object, so the URL stays the single source of truth: 

    import { refract } from "@refract/js";

const url = refract("hero.jpg", { width: 1200, format: "auto", quality: 80 });
// -> https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80

Parameter reference

Ten chainable parameters.

Seven are applied at the edge on request; fm, q, and dpr are negotiated server-side from the request itself.

Parameter Accepts Description Stage
w integer px Output width in pixels.
h integer px Output height in pixels.
fit cover, contain, fill, crop Resize mode. How the image is fitted to the target box.
fm jpeg, png, webp, avif, auto Output format. auto negotiates AVIF, then WebP, then JPEG from the Accept header. Server-side
q 1–100 (default 75) Output quality. Server-side
dpr 1–3 Device pixel ratio. Scales the output for high-density displays. Server-side
crop smart, center, edges Crop strategy. Smart crop keeps subjects in frame.
rot 90, 180, 270 Rotation in degrees, clockwise.
blur 0–100 Gaussian blur radius.
bg hex color Background fill for fit=contain letterboxing.

Caching & limits

One rate, one TTL, one network.

50 req/s

Rate limit per key, all tiers

30 days

Edge cache TTL for variants

41 locations

Global edge delivery

Purge

Instant purge by URL or tag — invalidate a single variant or an entire tagged set the moment the origin changes.