Media / foldkit-media
Choosing where images come from
A photo a user uploads, or one on another site, comes from a server or CDN
rather than your build. Image.view draws it the same way: instead of
...hero, you pass the photo's facts (ImageAsset, stored when it was
uploaded) and a provider, which writes the URL of each copy.
Under the hood, Picture.derive takes those three inputs — an ImageAsset, a
Provider, and a Layout — and computes every attribute (sources, img, and
the ratio) in memory as pure data.
| Layout | Candidates | sizes |
|---|---|---|
Fixed({ width }) | Ladder widths covering 1x and 2x | ${width}px |
Constrained({ width }) | Widths up to the one covering 2x | (min-width: ${width}px) ${width}px, 100vw |
FullWidth() | The whole ladder | 100vw |
A width above the original's own is described with the original's width, and only the first such width is offered so providers that skip upscaling avoid duplicate URLs.
Provider.cdnCgi({ zone?, widths?, quality? })— Cloudflare's/cdn-cgi/image/URLs on a zone with image resizing enabled. It picks the format fromAccept, so it writesimgdirectly. Akeymay be a path on the zone or an absolute URL.Provider.fromFiles(files, { sources, fallback })— variants a build already wrote, as a table of{ width, format, url }. Its ladder is the widths it has; missing variants are omitted fromsrcset.Provider.hosted({ baseUrl?, space?, sources?, fallback?, quality? })— this package's own server, for originals no CDN can fetch. A variant's URL is/_image/<sha-256>/w640.avif: the original is named by its content hash, so it is aProvider<HashedAsset>, and facts withouthashare a type error where the picture is derived. Decode stored facts with theHashedAssetSchema (an upload answers one), or narrow withisHashed. Because the format is in the URL, every cache keys on it directly.detect(url, { widths?, sources?, fallback?, quality? })fromfoldkit-media/unpic— an image on a host that resizes it (Shopify, Cloudinary, imgix, Contentful, and the rest unpic knows), through unpic, an optional peer. It returnsOption<Provider>: none for a host unpic lacks a provider for. By defaultimgasks forautoand the host picks the format fromAccept; a format requested as asourceis dropped on a host that ignores it (such as Shopify). The asset'skeyis the image's URL, and its size comes fromfactsOf(url)(see Reading an image's facts).tsimport { Option, Schema } from 'effect' import { ImageAsset, Layout, Picture, Provider } from 'foldkit-media' import { detect } from 'foldkit-media/unpic' const hero = Schema.decodeUnknownSync(ImageAsset)({ key: 'photos/hero.jpg', width: 2400, height: 1600, alpha: false, hash: null, placeholder: null, }) const picture = Picture.derive({ asset: hero, provider: Provider.cdnCgi(), layout: Layout.Constrained({ width: 720 }), }) Option.map(picture, ({ img }) => img.srcset) // "/cdn-cgi/image/width=320,format=auto,fit=scale-down/photos/hero.jpg 320w, …" const shopify = detect('https://cdn.shopify.com/s/files/1/0/products/shirt.jpg') Option.isSome(shopify) // true
A provider is a plain value (Provider.Provider): widths, the sources
formats offered before img, img's own fallback encoding, and a url
function returning Option<string>.