media-cdn

lib

image and video renditions cut at the edge by Cloudflare, at the size shown

npx shadcn add @ag/media-cdn

Already installed? Preview an update

npx shadcn add @ag/media-cdn --dry-run

Your installed source stays unchanged until you update it. How updates work

Latest changes · 2026-10-07

New: mediaCdn(host), the serving half of prepare-media: renditions cut at the edge on request by Cloudflare's transformations, on the host you name. image(src, { width, quality }) strips metadata and picks the browser's format at the width shown; frame(src, second, width) is a video's exact frame at a second, the picture macos's still wants. What is known ahead of time stays prepare-media's (files, once); what is known only when a page draws is this.

Updated 2026-10-07 · release notes

shelf media

cut at the edge

on request, on the host you name

{
  "image": "https://cdn.example.com/cdn-cgi/image/metadata=none,format=auto,width=1200,quality=82/uploads/photo.jpg",
  "frame": "https://cdn.example.com/cdn-cgi/media/mode=frame,time=12.5s,width=640/films/hero.mp4"
}

the demo above, verbatim

media-cdn.demo.tsx

import { Sample } from "@/app/samples"
import "@/registry/base-nova/ui/edge-fade"
import { mediaCdn } from "./media-cdn"

// #region renditions
const cdn = mediaCdn("https://cdn.example.com")
const urls = {
  image: cdn.image("https://cdn.example.com/uploads/photo.jpg", {
    width: 1200,
  }),
  frame: cdn.frame("https://cdn.example.com/films/hero.mp4", 12.5, 640),
}
// #endregion
export default function Demo() {
  return (
    <Sample
      name="renditions"
      with="renditions"
      title="cut at the edge"
      description="on request, on the host you name"
    >
      <pre className="ag-edge-fade-xy text-xs">
        {JSON.stringify(urls, null, 2)}
      </pre>
    </Sample>
  )
}

the source, every file an install writes

media-cdn.ts

// The serving half of the media pipeline: renditions cut at the edge, on
// request, by Cloudflare's transformations on the zone that serves the media.
// prepare-media makes what is known ahead of time, once, as files (an
// upload's poster at a chosen second, its previews); this makes what is known
// only when a page draws (an image at the width it is shown, a video's frame
// at the second a story rests on), each cut once and cached. No storage
// dependency: it builds URLs on a host the consumer names.
//
// Needs Image Transformations on the zone (`image`) and Media
// Transformations for video frames (`frame`).

export type MediaCdn = {
  /** An image for the page: metadata stripped (EXIF), the browser's best
   *  format, capped at `width` (default 1600) at `quality` (default 82). The
   *  original stays untouched. */
  image: (src: string, options?: { width?: number; quality?: number }) => string
  /** A video's frame at `second`, `width` pixels wide: a picture that must be
   *  the video's exact moment before the video has loaded (`macos`'s
   *  `still`). */
  frame: (src: string, second: number, width: number) => string
}

/** The renditions of the media served from `host` (an origin, no trailing
 *  slash: "https://cdn.example.com"). A `src` on another host is a
 *  contract violation and throws. */
export function mediaCdn(host: string): MediaCdn {
  const path = (src: string) => {
    if (!src.startsWith(`${host}/`))
      throw new Error(`media-cdn: ${src} is not on ${host}`)
    return src.slice(host.length + 1)
  }
  return {
    image: (src, { width = 1600, quality = 82 } = {}) =>
      `${host}/cdn-cgi/image/metadata=none,format=auto,width=${width},quality=${quality}/${path(src)}`,
    frame: (src, second, width) =>
      `${host}/cdn-cgi/media/mode=frame,time=${second}s,width=${width}/${path(src)}`,
  }
}