Media

A media image belongs to one workspace. The bytes live on the CDN. A document stores the original URL where it uses the image, in a field.media().

cover: https://cdn.backmatter.app/img/med_018f6b3e-7c2a-7b1d-8e4f-9a0b1c2d3e4f

That URL is the file as it was uploaded. JPEG, PNG, WebP, GIF, and AVIF are accepted, up to 20 MB. Studio, the chat, and the CLI write the same catalog.

field.image() is still any URL. field.media() accepts only an original catalog URL. A transform URL is not stored on the document.

Studio

The Media page is on the content rail. Upload from the button or by dropping files onto the page. Open an image for the lightbox. The context menu copies the original URL, or removes the image from the gallery. A document that already stores that URL keeps it.

A field.media() input has Choose. That opens the same gallery, and the document stores the original URL you pick.

The chat searches the catalog by filename. It can also copy an http or https image into the catalog, then write that original URL into the field.

CLI

upload and list use a personal token from login. url only prints a CDN URL.

backmatter login
backmatter media upload cover.jpg --workspace <id>
backmatter media list --q cover --workspace <id>
backmatter media url med_018f6b3e-7c2a-7b1d-8e4f-9a0b1c2d3e4f --width 800

login opens the browser. Approve it, and the token is stored in ~/.backmatter/credentials.json. The API is BACKMATTER_API_URL, or http://localhost:3001. The approval page is BACKMATTER_WEB_ORIGIN, or http://localhost:5173. --api and --web override those.

upload takes one or more files and prints one line each: the filename, a tab, and the original URL. list prints the count, then the same columns. --q keeps filenames that contain that text. Pass --workspace, or set BACKMATTER_WORKSPACE or BACKMATTER_WORKSPACE_ID (the same id as backmatter.config.ts). --api overrides the API stored at login.

url prints the CDN URL for an id. --width appends width and format=auto. --origin defaults to https://cdn.backmatter.app.

Transforms

Append Cloudflare's options as one path segment:

https://cdn.backmatter.app/img/med_018f6b3e-7c2a-7b1d-8e4f-9a0b1c2d3e4f/width=800,fit=cover,format=auto

The worker passes those names and values to Cloudflare Images. A site on any host embeds the URL. The resize runs on cdn.backmatter.app.

When format is omitted, the worker treats it as format=auto and chooses AVIF, WebP, or JPEG from the request's Accept header. The gallery thumbnail is width=400,format=auto. The lightbox is width=1200,format=auto. The catalog also lists 800 and 2000. Any other positive width is a URL you write yourself. backmatter media url with --width prints that form.

Each distinct option set on an image is one transform. A repeat of that same URL is served from cache.

onerror and slow-connection-quality belong to Cloudflare's /cdn-cgi/image/ URL, so they are refused here. border is an object on the Images binding and has no URL form, so it is refused too. baseline-jpeg is delivered as JPEG. format=json returns the stored file's width, height, and type, and does not transform it.

width=auto can take wbreakpoints, wmobile, and wdesktop. An unknown name, a duplicate, or a value outside that list is a 400, and the image is not transformed.