Cloudflare.Images reference

Images

Source: src/Cloudflare/Images/Images.ts

A Cloudflare Images binding for image transformation inside Workers — a Worker-only binding with no backing cloud resource.

Images is a single value that is at once the Binding.Service tag, the callable that produces an ImagesBinding, and the type. Declare it on a Worker’s env (it flows through InferEnv → cf.ImagesBinding) or yield* it inside an Effect-native Worker to attach the binding and obtain the ImagesClient.

Images: Effect-style Worker (recommended)

import { HttpServerRequest } from "effect/unstable/http/HttpServerRequest";

Cloudflare.Worker("ImageWorker", { main: import.meta.url },
  Effect.gen(function* () {
    const images = yield* Cloudflare.Images.Images("PIPELINE");
    return {
      fetch: Effect.gen(function* () {
        const request = yield* HttpServerRequest;
        const info = yield* images.info(request.stream);
        return yield* HttpServerResponse.json(info);
      }),
    };
  }).pipe(Effect.provide(Cloudflare.Images.ImagesBinding)),
);

Images: Binding to a Worker (declarative)

export const Worker = Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  env: { MEDIA: Cloudflare.Images.Images("PIPELINE") },
});

export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
//   { MEDIA: ImagesBinding }

Images: Local development

// Default: transforms run locally via Sharp under `alchemy dev` and
// hosted images are stored on disk. Alchemy.remote() opts the binding
// into the real Images service instead — in an Effect-native Worker:
const images = yield* Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote());

// or declared on an async Worker's env:
env: { IMAGES: Cloudflare.Images.Images("IMAGES").pipe(Alchemy.remote()) }

SigningKey

Source: src/Cloudflare/Images/SigningKey.ts

A Cloudflare Images signing key — an HMAC key used to generate signed image delivery URLs (?sig= tokens) for images that require signed URLs.

Cloudflare allows at most two keys per account, supporting a create-second/migrate/delete-first rotation model, and refuses to delete the last remaining key. Re-PUTting an existing key name rotates (i.e. regenerates) its value, so this resource is existence-only: once the key exists, redeploys never re-PUT and the key material stays stable.

Requires the Cloudflare Images subscription; accounts without it receive the typed ImagesAccessNotEnabled error.

SigningKey: Creating a Signing Key

Key with a generated name

const key = yield* Cloudflare.Images.SigningKey("UrlSigner", {});

Key with an explicit name

const key = yield* Cloudflare.Images.SigningKey("UrlSigner", {
  name: "my-app-signer",
});

SigningKey: Using the key

// The key material is redacted — pass it to your URL signer:
const secret = key.value; // Redacted<string>

Variant

Source: src/Cloudflare/Images/Variant.ts

A Cloudflare Images variant — a named resizing preset (e.g. thumbnail, hero) applied when serving images from Cloudflare Images.

A variant is identified by its name within an account (up to 100 variants per account). The name is the URL segment used to request the variant, so it is immutable — changing it triggers a replacement. All resizing options (fit, width, height, metadata, neverRequireSignedURLs) are mutable in place.

Note: every Images-enabled account has a built-in public variant. Do not manage public with this resource — Cloudflare silently ignores deletes of the built-in variant, so destroy would not actually remove it.

Variant: Creating a Variant

Thumbnail variant

// Variant names are alphanumeric only (no hyphens/underscores).
const thumbnail = yield* Cloudflare.Images.Variant("thumbnail", {
  fit: "cover",
  width: 100,
  height: 100,
});

Hero variant with explicit name and metadata

const hero = yield* Cloudflare.Images.Variant("HeroImage", {
  name: "hero",
  fit: "scale-down",
  width: 1920,
  height: 1080,
  metadata: "copyright",
});

Variant: Signed URLs

// Serve this variant without a signature even when the image itself
// requires signed URLs (e.g. for public thumbnails of private images).
const preview = yield* Cloudflare.Images.Variant("preview", {
  fit: "contain",
  width: 320,
  height: 240,
  neverRequireSignedURLs: true,
});