Medien und Bilder

Medien hochladen

Medien laden Sie entweder in der CMS-UI (Mediathek) oder per CLI hoch:

# Einzelne Dateien
hcms media upload --file ./bilder/hero.jpg --file ./bilder/logo.svg
 
# Ganzer Ordner in eine Bibliotheks-Ablage
hcms media upload --dir ./bilder --folder Kampagne2026
 
# Mediathek durchsuchen
hcms media list --search hero --limit 40

Jede Datei wird einzeln verarbeitet; ein Fehler bricht den restlichen Upload nicht ab. Maximale Dateigrösse pro Upload: 50 MB.

Bilder im Frontend ausliefern

Media-Felder (image, file, gallery) enthalten standardmässig nur eine Media-ID – oder ein eingebettetes Objekt mit url, wenn der Eintrag mit populate geladen wurde. Der Helfer cmsMediaUrl (aus cms/client.ts) löst beide Fälle auf:

export function cmsMediaUrl(
  value: unknown,
  opts: TransformOptions = {}
): string | undefined

Verhalten:

• Eingebettetes Media-Objekt mit url → gibt diese url unverändert zurück.
• Reine Media-ID (String) → baut eine Transform-URL. Ist weder w noch h gesetzt, wird { w: 1600 } als Standardbreite verwendet (der Transform-Endpunkt verlangt zwingend w oder h).
• Sonst → undefined (die Komponente sollte dann nichts rendern).

const src = cmsMediaUrl(entry.data.cover, { w: 800, fm: "webp" })
if (src) return <img src={src} alt="" />

Transform-Optionen

Die zugrundeliegende URL sieht so aus:

https://acme.scorebase.ch/headless/api/v1/media/<id>/transform?w=640&fm=webp

Der Transform-Endpunkt ist öffentlich (kein Token nötig), liefert immer eine Weiterleitung auf eine unveränderlich gecachte Variante, skaliert nie hoch und ist auf 60 Anfragen pro Minute und IP begrenzt.

Responsive Bilder

Das SDK bietet zusätzlich srcSet und imgProps für responsive Bilder. Die Standard-Breitenstufen sind 320, 640, 960, 1280, 1920:

import { imgProps } from "@kailua-packages/headless-sdk"
 
<img {...imgProps(HCMS_URL, media, { sizes: "(max-width: 768px) 100vw, 800px" })} />

Feste Upload-Varianten

Beim Upload erzeugt das CMS zusätzlich feste Varianten, die (bei populate) unter variants[] eines Media-Objekts liegen:

Tipp: Verwenden Sie im ganzen Projekt konsequent cmsMediaUrl statt roher URLs – so profitieren alle Bilder automatisch von Transform und Caching.