---
order: 7
section: features
title: Assets
description: >-
  Deklarieren Sie validierte Asset-Felder mit field.asset(), schränken Sie Pfade
  und Formate ein und lösen Sie diese beim Lesen in öffentliche URLs auf.
noindex: false
canonicalPath: /de/docs/assets
---
Scribe behandelt statische Assets (aktuell Bilder) als erstklassige, im Schema deklarierte Referenzen und nicht als lose Zeichenketten. Das Grundprinzip: **Komponenten bauen Asset-URLs niemals durch das Verketten von Strings zusammen.** Im Frontmatter wird eine kanonische *Quellreferenz* gespeichert. Die Runtime löst diese beim Laden in die tatsächliche *Auslieferungs-URL* auf. Genau diese eine Indirektion sorgt dafür, dass sich `publicPath`, CDNs und Content-Hashing einfach als Konfiguration einbinden lassen, ohne dass Code-Migrationen nötig sind.

## Configuration

Die Konfigurationsgruppe `assets` legt fest, wo die Quelldateien liegen und wie sie ausgeliefert werden. Das einfache `assetsDir` funktioniert weiterhin als veralteter Alias für `{ dir: assetsDir }`.

```ts
export default defineConfig({
  // ...
  assets: {
    dir: "public",            // Speicherort der Quelldateien, relativ zu rootDir. Standard: "public".
    publicPath: "/",          // URL-Präfix für die Auslieferung. Ein Pfad ("/static/") oder ein CDN-Origin. Standard: "/".
    managedDirs: ["/blog-images"], // Zusätzliche Scribe-verwaltete Webpfad-Roots, die von keinem field.asset() abgedeckt werden.
  },
});
```

`publicPath` folgt hierbei der bekannten Konvention von webpack und Vite. Einträge unter `managedDirs` sind **Quellverzeichnisse** (Source Roots). Es handelt sich um Verzeichnisse, die in MDX-Inhalten referenziert werden, aber nicht an ein spezifisches Asset-Feld gebunden sind.

## `field.asset()`

```ts
import { field } from "scribe-cms";

const garmentSchema = z.object({
  title: field.translatable(z.string()),
  productImage: field.asset({
    dir: "/try-on/garments",   // Wert muss sich unter diesem Webpfad befinden
    formats: ["webp"],          // Erlaubte Dateiendungen
    maxKB: 150,                 // Dateigrößen-Budget (gibt eine Warnung aus)
    optional: false,            // Standardwert
  }),
});
```

Wie bei `field.relation()` **werden Einschränkungen im Optionen-Objekt definiert und nicht über verkettete Zod-Methoden**. Durch Chaining würde das Schema geklont und die Metadaten gingen verloren. Asset-Felder sind immer struktureller Natur: Asset-Pfade werden niemals an die Übersetzung übergeben.

| Option | Typ | Bedeutung |
| --- | --- | --- |
| `dir` | `string` | Präfix für den Webpfad, unter dem der Wert liegen muss. Deklariert zudem ein Managed Root. |
| `template` | `string` | Vorlage für abgeleitete Pfade, z. B. `"/try-on/garments/{slug}/product.webp"`. `{slug}` ist der englische Slug des Eintrags. Wenn gesetzt, kann das Frontmatter-Feld komplett weggelassen werden, und der Loader füllt es automatisch aus. Ein expliziter Wert überschreibt die Vorlage (ideal für das bewusste Teilen von Assets zwischen Einträgen). |
| `formats` | `string[]` | Erlaubte Dateiendungen (kleingeschrieben, ohne Punkt). Bei Verstößen gibt es eine Validierungswarnung. |
| `maxKB` | `number` | Budget für die Dateigröße. Bei Verstößen gibt es eine Validierungswarnung. |
| `optional` | `boolean` | Feld darf fehlen (nur sinnvoll ohne `template`). Wenn ein Wert angegeben ist, die Datei aber fehlt, führt das weiterhin zu einem Fehler. |

Der Frontmatter-Wert ist ein **relativer Webpfad** bezogen auf `assets.dir`, z. B. `/try-on/garments/denim-flare/product.webp`. Dies entspricht der gleichen Konvention wie bei einfachen Bild-Strings. Es wird kein neues URI-Schema benötigt. Auf der Festplatte speichert das Frontmatter die Quellreferenz (oder gar nichts, falls eine Vorlage genutzt wird). Aufgelöste URLs existieren nur im Runtime-Output. Statische Exporte, Rohdaten und auch das Übersetzungssystem sehen immer nur die Quellwerte.

## Loader resolution

Wenn die Runtime ein Dokument lädt, durchläuft sie das Schema auf der Suche nach Asset-Feldern und führt für jedes Feld folgende Schritte aus:

1. Fehlt der Frontmatter-Wert und das Feld hat ein `template`, wird der Pfad aus der Vorlage generiert (`{slug}` wird zum englischen Slug).
2. Das Präfix `assets.publicPath` wird vorangestellt (verbunden ohne doppelte Schrägstriche, absolute Ursprünge für `publicPath` werden unterstützt).

Konsumenten erhalten so direkt die fertigen URLs, ohne zusätzliche Aufrufe:

```ts
const garment = scribe.garment.get("denim-flare");
garment.frontmatter.productImage;
// "/try-on/garments/denim-flare/product.webp"                       (publicPath "/")
// "https://cdn.example.com/try-on/garments/denim-flare/product.webp" (CDN publicPath)
```

Die Auflösung erfolgt erst, nachdem strukturelle Felder mit den Lokalisierungsdokumenten zusammengeführt wurden. So erhält jede Spracheingabe die korrekt aufgelösten Werte aus der englischen Quelle.

### `scribe.assets.url(ref)`

Ein Fluchtweg für Bilder im MDX-Body und Ad-hoc-Fälle. Es wendet `publicPath` auf eine rohe Referenz an:

```ts
scribe.assets.url("/blog-images/hero.webp"); // publicPath wird angewandt
```

Sie können Assets auch direkt im MDX-Body über das [Inline-Token `asset`](/docs/inline-tokens) referenzieren. Dieses wird beim Lesen auf exakt die gleiche Weise aufgelöst.

## Validation

Der Befehl `scribe validate` prüft deklarierte Asset-Felder:

- **Fehlende Datei bei einem Pflicht-Asset-Feld**: Fehler (blockiert den Build, genau wie eine ins Leere laufende Pflichtrelation).
- **Fehlende Datei bei einem `optional`-Feld mit vorhandenem Wert**: Ebenfalls ein Fehler. `optional` bedeutet lediglich, dass das *Feld* fehlen darf, aber nicht, dass ein angegebener Pfad auf eine nicht existierende Datei verweisen darf.
- **Wert außerhalb des festgelegten `dir`**: Fehler.
- **Dateiendung nicht in `formats`**: Warnung.
- **Datei größer als `maxKB`**: Warnung.
- Bei Feldern mit Vorlagen wird der *generierte* Pfad validiert. Die Datei muss existieren, auch wenn das Frontmatter den Wert weglässt.

Die Meldungen enthalten immer die Zuordnung zum jeweiligen Feld, z. B. `garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found`. Unabhängig davon werden Strings in Frontmatter und MDX-Bodies, die wie Bilder aussehen, heuristisch erfasst und bei Fehlen weiterhin als Warnungen gemeldet. Dies deckt Bilder im Body ab, ohne dass eine Migration erforderlich ist.

## Studio

Das [Studio](/docs/studio) zeigt Assets im reinen Lesemodus (Read-only) an:

- Der **Entry Inspector** rendert Asset-Felder als Bildvorschau samt aufgelöster URL, Dateigröße und Abmessungen. Fehlt eine Datei, wird ein rotes Abzeichen angezeigt.
- Der **Asset Browser** (`/assets`) bietet ein Thumbnail-Raster pro Managed Root. Jedes Asset wird mit Pfad, Größe, Abmessungen und einer "Referenziert von"-Liste aller darauf verweisenden Einträge und Felder dargestellt. Abzeichen markieren unreferenzierte Assets (potenzielle Waisen), fehlende aber referenzierte Dateien sowie Assets, die zu groß sind oder vom Format abweichen.
- Die **Gallery View** ermöglicht es jedem Typ mit einem Asset-Feld, die Eintragsliste als Kartenraster darzustellen. Dies ist eine ideale QS-Wand für generierte Bilder.