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.

LayoutCandidatessizes
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 ladder100vw

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 from Accept, so it writes img directly. A key may 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 from srcset.
  • 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 a Provider<HashedAsset>, and facts without hash are a type error where the picture is derived. Decode stored facts with the HashedAsset Schema (an upload answers one), or narrow with isHashed. Because the format is in the URL, every cache keys on it directly.
  • detect(url, { widths?, sources?, fallback?, quality? }) from foldkit-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 returns Option<Provider>: none for a host unpic lacks a provider for. By default img asks for auto and the host picks the format from Accept; a format requested as a source is dropped on a host that ignores it (such as Shopify). The asset's key is the image's URL, and its size comes from factsOf(url) (see Reading an image's facts).
    ts
    import { 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>.