Jetzt mit KI-gestütztem Page Building über den MCP-Server

Medien

Bilder und Dateien liegen in der Medienbibliothek des Workspace. Wie Blöcke sie referenzieren, warum jeder Upload seine eigene URL bekommt und was das beim Ersetzen bedeutet.

Medien liegen auf Workspace-Ebene, nicht auf Seitenebene. Eine Bibliothek, in Ordnern organisiert, geteilt von jeder Seite und jedem Block.

Das Medienfeld

Ein Block erreicht ein Asset über fields.media:

export const imageProps = {
  src: fields.media({ label: "Image", required: true }),
  alt: fields.text({ label: "Alt text" }),
};

Gespeichert wird ein URL-String, keine ID und kein Objekt. Deine Komponente bekommt ihn einsatzbereit:

function ImageBlock({ content }) {
  if (!content.src) return null;
  return <img src={content.src} alt={content.alt ?? ""} />;
}

Weil der Wert eine schlichte URL ist, kostet ein Medienfeld beim Rendern nichts - kein Lookup, kein Auflösungsschritt, kein Zustand, in dem das Bild noch lädt.

Jeder Upload bekommt seine eigene URL

Hochgeladene Assets werden von einem CDN-Host ausgeliefert, mit einem Hash im Pfad:

https://assets.cmssy.io/{workspaceId}/78aa0167-cmssy-og-default.png

Dieser Hash gilt pro Upload. Genau das macht Assets unveränderlich und dauerhaft cachebar - hat aber eine Folge, die man meist auf die harte Tour lernt:

Einen Ersatz hochzuladen aktualisiert die Blöcke nicht, die auf die alte Datei zeigen. Ein neuer Upload ist eine neue URL; bestehende Blöcke behalten die alte und rendern weiter das alte Bild. Wenn du ein Logo getauscht hast und die Site zeigt weiter das vorherige, ist nichts falsch gecacht - die Blöcke zeigen schlicht dorthin, wohin sie immer zeigten.

Ein Ersetzen an Ort und Stelle gibt es nicht: Die Medien-Tools sind Auflisten, Hochladen und Verschieben - eine neue Datei bedeutet also immer eine neue URL. Das Mittel ist, die Blöcke neu zuzuweisen: ein Suchen-und-Ersetzen über Blockinhalte, worin der MCP-Server gut ist.

Die praktische Folge lohnt sich einzuplanen. Ein Asset, auf das viele Seiten verweisen - ein Logo, ein Standard-OG-Bild - lässt sich billiger tauschen, wenn es über die Site-Config oder einen einzigen Block läuft, statt in zwanzig Stellen kopiert zu sein.

Ordner

Ordner sind ein flacher Baum mit parentId. Sie ordnen die Bibliothek für Menschen; sie sind nicht Teil der URL, ein Verschieben bricht also nichts, was darauf zeigt.

Über MCP kannst du auflisten, anlegen, umbenennen, löschen und verschieben - was große Umsortierungen skriptbar macht statt zu einem Nachmittag Drag-and-drop.

Next.js-Bilder

Assets kommen von einem anderen Origin als deine App, next/image lehnt sie also ab, bis der Host erlaubt ist:

// next.config.mjs
const nextConfig = {
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "assets.cmssy.io" },
    ],
  },
};

Ein Wildcard hostname: "**" funktioniert und wird in der Referenz-App genutzt, lässt aber jeden HTTPS-Host durch deinen Bildoptimierer. Den Asset-Host zu nennen ist die engere Wahl und kostet eine Zeile.

Alt-Text ist Inhalt

Kombiniere jedes fields.media mit einem Textfeld für Alt-Text und lass die Redaktion es füllen. Alt-Text beschreibt, was das Bild in diesem Kontext bedeutet - dasselbe Foto braucht in einer Case Study anderen Alt-Text als in einer Logo-Wand. Es kann keine Eigenschaft der Datei sein, deshalb gehört es an den Block, nicht in die Bibliothek.

Nächste Schritte