Catalogue des formats d'image

La référence complète pour comment les images circulent dans Flexweg CMS — de l'upload à l'URL publique.

Pour des conseils côté auteur de thème sur la déclaration des formats, voir Créer des thèmes → Variantes d'image. Pour l'usage côté visiteur dans les blocs d'éditeur, voir Éditeur → Blocs de cœur.

Le pipeline

Utilisateur choisit le fichier dans la Médiathèque
            ↓
Processing côté navigateur dans services/imageProcessing.ts
            ↓
Création de chaque variante en WebP via Canvas API
            ↓
Upload de chaque variante sur Flexweg via l'API Files
            ↓
Création du document Media en base avec map des variantes
            ↓
Médiathèque affiche le média comme disponible

Tout se passe dans le navigateur de l'admin qui upload. Pas de service externe, pas de queue.

Variantes générées

À chaque upload, le pipeline génère :

Variantes du thème actif (déclarées dans manifest.imageFormats)

Par défaut, le thème déclare typiquement :

• thumbnail : 400×400 cover
• small : 600×600 contain
• medium : 1200×1200 contain
• large : 1600×1600 contain (ou plus selon le thème)

Trois variantes admin-only (toujours générées)

• admin-thumb — 72×72 cover. Pour les avatars utilisateurs et les vignettes de listing dans l'admin.
• admin-preview — 800×800 contain. Pour le panneau de détails de la médiathèque.
• admin-original — 2000×2000 contain, qualité 90. Source de re-crop préservée : si vous changez de thème plus tard et que le nouveau thème demande des variantes qui n'existaient pas, pickFormat retombe sur celle-ci.

Format de sortie

Par défaut WebP (qualité 80). Couvre :

• 95%+ des navigateurs modernes (Safari 14+, Chrome 32+, Firefox 65+)
• Meilleur ratio compression / qualité que JPEG
• Support transparence (alpha channel)

Pour un thème qui doit servir des très vieux navigateurs (IE11, Safari 13), surchargez outputFormat: "jpeg" dans le manifest.

SVG : pas de processing

Les SVG sont uploadés tels quels :

• Pas de pipeline de variantes (un SVG est déjà vectoriel)
• DOMPurify côté admin neutralise les scripts malveillants
• Stockés à media/<year>/<month>/<slug>-<hex>/original.svg

Côté thème, rendre via <img> ou inline via dangerouslySetInnerHTML. Au choix.

Stockage Flexweg

media/
  2026/
    05/
      red-roses-fxr8sd/
        admin-thumb.webp
        admin-preview.webp
        admin-original.webp
        thumbnail.webp
        small.webp
        medium.webp
        large.webp

Chaque média a son propre dossier identifié par <slug>-<hex> :

• <slug> est le nom de fichier normalisé via slugify()
• <hex> est un suffixe aléatoire 6 caractères. Collisions impossibles par construction.

Donc deux uploads du même fichier (par exemple photo.jpg deux fois) produisent deux dossiers différents.

URL publique d'une variante

https://monsite.flexweg.com/media/2026/05/red-roses-fxr8sd/medium.webp

L'admin construit l'URL via mediaToView(media) qui retourne :

{
  alt: "Red roses",
  caption: undefined,
  default: "/media/2026/05/red-roses-fxr8sd/medium.webp",
  formats: {
    "admin-thumb": { url, width, height },
    "admin-preview": { url, width, height },
    "admin-original": { url, width, height },
    "thumbnail": { url, width, height },
    "small": { url, width, height },
    "medium": { url, width, height },
    "large": { url, width, height },
  }
}

pickFormat et sa chaîne de fallback

import { pickFormat } from "@flexweg/cms-runtime";

const variant = pickFormat(view, "small");
// view.formats["small"] si existe
// → sinon view.formats[defaultFormat] si existe
// → sinon le format avec la plus grande area
// → sinon { url: "", width: 0, height: 0 }

Donc votre template ne crashe jamais sur un média ancien qui n'a pas la variante demandée.

Tailles typiques par variante

Image source 4000×3000 photo JPEG (5 Mo) :

Total : ~500 Ko sur Flexweg pour une image source de 5 Mo. Économie ×10.

Compression et qualité

quality est sur l'échelle 0-100. La qualité par défaut est 80 (bonne pour la plupart des usages). Pour admin-original, qualité 90 (pour la fidélité de re-crop).

Pour un thème éditorial où la qualité d'image compte, mettez 85-90 sur les variantes affichées. Pour un thème vitrine / SaaS où le poids prime, 75-80 suffit.

Re-traitement des variantes

Aujourd'hui pas d'UI pour re-générer rétroactivement les variantes manquantes. Si vous changez imageFormats du thème :

• Les nouveaux uploads ont les nouvelles variantes
• Les anciens uploads ne les ont pas — pickFormat retombe sur la plus grande disponible

Workaround : re-uploader chaque média manuellement. Ou écrire un script qui itère sur useCmsData().media, appelle processImage(file, newFormats), upload les nouvelles variantes.

Pas de download de l'original

L'image source uploadée par l'utilisateur n'est pas conservée. Seules les variantes (incluant admin-original) le sont. Donc :

• Pas de bouton "Télécharger l'original" dans la médiathèque
• admin-original (2000×2000 contain) est ce qu'il y a de plus proche
• Pour des sites éditoriaux où on veut garder l'original 4K+, c'est une limitation à connaître

Workaround : conservez vos originaux en dehors du CMS (Drive, Dropbox, etc.).

Performance d'upload

Le processing est synchrone dans le navigateur de l'utilisateur. Une image 5 Mo prend ~2-5 secondes (selon CPU). L'utilisateur voit un spinner pendant.

Pour des uploads en masse (50+ images), le pipeline les traite en série pour ne pas saturer le navigateur. Comptez ~3 min pour 50 images de 5 Mo.

Storage utilisé

Le plan Flexweg de base offre typiquement 10 Go de storage. Pour un site avec 500 médias (5 variantes × 500 = 2500 fichiers, ~0.5 Mo moyenne / fichier total = ~1.5 Go), vous êtes largement dans les clous.

Le plugin flexweg-metrics surface la consommation actuelle vs le quota dans une carte du tableau de bord.