Skip to content
Rendorix

Using presets

A preset is a name you give to a bundle of transform parameters—hero, card, avatar—so your app talks in roles (“this is a hero image”) instead of raw w / h / f / q everywhere. That is the main ergonomic win of Rendorix alongside signing: same idea as Tailwind’s theme tokens, but for image dimensions and format (Client library).

App code vs. the wire

Section titled “App code vs. the wire”
  • With @rendorix/client: you pass preset: "hero" (and optional overrides) to img(). The library looks up presets.hero in your createRendorix config, merges overrides, validates, then emits a URL whose query contains the concrete fields (w, h, f, q, …) plus exp and s—not a separate p= parameter. See Generating image URLs.
  • Custom or non-Node stacks: you might still use a p=hero-style query if your edge and signer were built that way. The signer and CloudFront Function must agree; do not mix wire formats.

In HTML you only ever drop in the final string from img() (or your manual builder):

<img src={src} width="1200" height="630" alt="" />

Use real width / height (or CSS aspect box) for layout stability; they should match what the preset delivers.

Combining presets with inline options

Section titled “Combining presets with inline options”

With the Node client, inline w, h, f, q on img() override the preset’s fields for that call (see Overrides). Example: rx.img(key, { preset: "card", w: 320 }) narrows width while keeping the rest of card.

Per-environment preset lists

Section titled “Per-environment preset lists”
  • Production — Only approved preset keys in createRendorix({ presets }) (and the same names your edge allows if it also knows preset names—often it only sees resolved numbers).
  • Staging — Extra keys (e.g. debugXL) via a separate config or env-gated module.

Typo-safe TypeScript configs: unknown preset: "herp" can be a compile-time error if you type presets narrowly.

Deprecation and migration

Section titled “Deprecation and migration”

When renaming or replacing a preset (hero → hero_v2):

  1. Add the new entry in config and update call sites to preset: "hero_v2".
  2. Keep old URLs working until cache / email lifetimes allow (old signed links may still request the old transform).
  3. Monitor unknown_preset errors from the client or 403s at the edge after removal.

Avoid reusing a name for a completely different look without a version bump—silent visual drift is hard to trace.

Section titled “Related reading”