---
order: 7
section: features
title: Ressources
description: >-
  Déclarez des champs de ressources validés avec field.asset(), imposez des
  contraintes de chemins et de formats, et résolvez-les en URL publiques au
  moment de la lecture.
noindex: false
canonicalPath: /fr/docs/assets
---
Scribe traite les fichiers statiques (actuellement les images) comme des références de premier ordre déclarées dans le schéma, et non comme de simples chaînes de caractères. Le principe fondamental est le suivant : **les composants ne construisent jamais d'URL de ressources par concaténation de chaînes.** Le frontmatter stocke une *référence source* canonique, et le runtime la résout pour obtenir l'*URL servie* au moment du chargement. Cette unique indirection permet d'intégrer `publicPath`, les CDN et le hachage de contenu par simple configuration, sans avoir à remanier le code.

## Configuration

Le groupe de configuration `assets` déclare l'emplacement des fichiers sources et la manière dont ils sont servis. L'option simple `assetsDir` fonctionne toujours, mais reste un alias obsolète pour `{ dir: assetsDir }`.

```ts
export default defineConfig({
  // ...
  assets: {
    dir: "public",            // emplacement des fichiers sources sur le disque, relatif à rootDir. Par défaut "public".
    publicPath: "/",          // préfixe d'URL sous lequel ils sont servis. Un chemin ("/static/") ou une origine CDN. Par défaut "/".
    managedDirs: ["/blog-images"], // racines de chemins web supplémentaires gérées par Scribe, non couvertes par un field.asset()
  },
});
```

L'option `publicPath` suit la convention webpack/Vite pour ce concept. Les entrées `managedDirs` sont des **racines sources** : il s'agit des répertoires référencés dans les corps MDX qui ne sont pas liés à un champ de ressource spécifique.

## `field.asset()`

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

const garmentSchema = z.object({
  title: field.translatable(z.string()),
  productImage: field.asset({
    dir: "/try-on/garments",   // la valeur doit se trouver sous ce chemin web
    formats: ["webp"],          // liste blanche des extensions
    maxKB: 150,                 // budget de taille (avertissement)
    optional: false,            // par défaut
  }),
});
```

Tout comme pour `field.relation()`, **les contraintes se trouvent dans l'objet d'options, et non dans des méthodes Zod chaînées**. Le chaînage clone le schéma et supprime les métadonnées. Les champs de ressources sont toujours structurels : les chemins des fichiers ne sont jamais envoyés au traducteur.

| Option | Type | Signification |
| --- | --- | --- |
| `dir` | `string` | Préfixe de chemin web sous lequel la valeur doit se trouver. Déclare également une racine gérée. |
| `template` | `string` | Modèle de chemin dérivé, par exemple `"/try-on/garments/{slug}/product.webp"`. `{slug}` correspond au slug anglais de l'entrée. Lorsqu'il est défini, le champ frontmatter peut être totalement omis et le chargeur s'en occupe. Une valeur explicite surcharge le modèle (partage intentionnel entre les entrées). |
| `formats` | `string[]` | Extensions autorisées (en minuscules, sans point). Toute violation déclenche un avertissement de validation. |
| `maxKB` | `number` | Budget de taille de fichier. Toute violation déclenche un avertissement de validation. |
| `optional` | `boolean` | Le champ peut être absent (n'a de sens que sans `template`). Une valeur présente dont le fichier est introuvable reste une erreur. |

La valeur du frontmatter est un **chemin web relatif à la racine** dans `assets.dir`, par exemple `/try-on/garments/denim-flare/product.webp`. Elle utilise la même convention qu'une simple chaîne d'image, sans nouveau schéma d'URI. Sur le disque, le frontmatter stocke la référence source (ou rien du tout si un modèle est utilisé). Les URL résolues n'existent que dans la sortie du runtime. Les exports statiques ou bruts ainsi que le traducteur voient toujours les valeurs sources.

## Résolution par le chargeur

Lorsque le runtime charge un document, il parcourt le schéma à la recherche de champs de ressources et, pour chacun d'eux :

1. Si la valeur du frontmatter est absente et que le champ possède un `template`, il matérialise le chemin à partir de ce modèle (`{slug}` devient le slug anglais).
2. Il préfixe `assets.publicPath` (assemblé sans doubles barres obliques, les `publicPath` à origine absolue sont pris en charge).

Les consommateurs obtiennent ainsi les URL finales sans aucun appel supplémentaire :

```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" (publicPath CDN)
```

La résolution s'exécute après la fusion des champs structurels sur les documents localisés. Ainsi, chaque paramètre régional obtient des valeurs résolues à partir de la source anglaise.

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

Il s'agit d'une solution de contournement pour les images du corps MDX et les cas spécifiques, appliquant `publicPath` à une référence brute :

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

Vous pouvez également référencer des ressources directement dans les corps MDX avec le [jeton en ligne `asset`](/docs/inline-tokens), qui se résout de la même manière lors de la lecture.

## Validation

`scribe validate` vérifie les champs de ressources déclarés :

- **Fichier manquant pour un champ de ressource requis** : erreur (bloque la compilation, à l'image d'une relation requise orpheline).
- **Fichier manquant pour un champ `optional` avec une valeur présente** : erreur également. L'option `optional` signifie que le *champ* peut être absent, et non qu'un chemin indiqué peut être erroné.
- **Valeur en dehors du `dir` du champ** : erreur.
- **Extension absente de `formats`** : avertissement.
- **Fichier dépassant `maxKB`** : avertissement.
- Les champs basés sur un modèle valident le chemin *matérialisé*. Le fichier doit exister même si le frontmatter omet la valeur.

Les messages incluent l'attribution du champ, par exemple `garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found`. Par ailleurs, les chaînes ressemblant à des images, collectées de manière heuristique à partir du frontmatter et des corps MDX, sont toujours signalées par des avertissements lorsqu'elles sont manquantes. Cela permet de couvrir les images du corps du texte sans aucune migration.

## Studio

Le [studio](/docs/studio) présente les ressources en lecture seule :

- **L'inspecteur d'entrée** affiche les champs de ressources sous forme d'aperçus d'images avec l'URL résolue, la taille du fichier et ses dimensions. Un fichier manquant affiche un badge rouge.
- **L'explorateur de ressources** (`/assets`) affiche une grille de miniatures par racine gérée. Chaque ressource est accompagnée de son chemin, de sa taille, de ses dimensions et d'une liste « référencé par » de chaque entrée et champ pointant vers elle. Des badges signalent les ressources non référencées (candidates orphelines), manquantes mais référencées, surdimensionnées et celles dont le format a dérivé.
- **La vue galerie** permet à tout type possédant un champ de ressource d'afficher sa liste d'entrées sous forme de grille de cartes, formant ainsi un mur de contrôle qualité pour les images générées.