manual · refract(1)

man refract

Quickstart and reference. Everything below is a command and its output — the same session the rest of the site is written in.

Name

refract — on-the-fly image transforms, optimization, and global edge delivery, driven by URL parameters.

Synopsis

Point Refract at a source path on your origin and append parameters. They chain in any order.

https://demo.refract.dev/<source>?<param>=<value>&…
https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80

Description

Refract transforms, optimizes, and delivers images from a URL. There is no re-upload: you point it at an existing image origin, and originals are fetched on demand and cached at the edge — never stored permanently.

A request is a source path plus parameters. The edge negotiates the best format from your request's Accept header, applies the transform, caches the variant, and answers from the nearest of 41 locations.

Quickstart

  1. [1]

    Create an API key and connect your image origin.

  2. [2]

    Request your first transform — the request-form URL, straight from the browser or curl.

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

    Automate with the SDK.

    step 3 — automate @refract/js 
    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

Options

Ten parameters. Three — fm, q, dpr — are chosen at the edge and marked negotiated.

Name Values Description
w integer, px Target width.
h integer, px Target height.
fit cover · contain · fill · crop Resize mode.
fm jpeg · png · webp · avif · auto negotiated Output format. auto picks AVIF → WebP → JPEG from Accept.
q 1–100, default 75 negotiated Quality.
dpr 1–3 negotiated Device pixel ratio.
crop smart · center · edges Crop strategy. smart keeps the subject in frame.
rot 90 · 180 · 270 Rotation, degrees.
blur 0–100 Gaussian blur.
bg hex color Background fill for fit=contain.

Limits

Rate limit: 50 requests per second, per key — the same on every tier. Transformed variants are cached at the edge for 30 days; purge instantly by URL or by tag.

rate limit — 50 req/s/key 429 
$ # the 51st request in one second, same key
HTTP/2 429
retry-after: 1
x-ratelimit-limit: 50   # requests/second/key — all tiers

Examples

resize and let the edge choose the format

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

a square thumbnail, subject kept in frame

https://demo.refract.dev/hero.jpg?w=600&h=600&fit=crop&crop=smart

contain on a fill color, softly blurred

https://demo.refract.dev/hero.jpg?w=800&fit=contain&bg=F1EEEE&blur=20