Référence Runtime API

@flexweg/cms-runtime est le pont entre l'admin et les plugins / thèmes externes. Il expose :

React + famille (pour que les bundles externes partagent l'instance React de l'admin)
i18next (pour que l'état de traduction soit partagé)
L'API plugin (filtres, actions, enregistrement de blocs / cartes / cibles de regen)
Helpers de cœur (slug, média, markdown, icônes sociales, render)
Client API Files de Flexweg (uploadFile, deleteFile, listFiles, …)
Helpers CRUD du backend (fetchAllPosts, createPost, updateMedia, … — agnostiques du backend Firebase / SQLite via les dispatchers)
Points d'entrée du publisher (publishPost, buildPublishContext)
Helpers de réglages (updatePluginConfig, updateThemeConfig)
Primitives UI (EntityCombobox, FontSelect, MediaPicker)
Hooks + contexts (useCmsData, useAuth, useAllPosts)

Cette page est la liste complète des exports avec ce que chacun fait. Pour des conseils pratiques, voir Créer des plugins et Créer des thèmes.

Versioning de l'API

Le runtime expose deux constantes de version :

import { FLEXWEG_API_VERSION, FLEXWEG_API_MIN_VERSION } from "@flexweg/cms-runtime";

apiVersion dans votre manifest.json est comparé à [FLEXWEG_API_MIN_VERSION, FLEXWEG_API_VERSION] au moment de l'installation + à chaque boot. Les bundles hors-range sont skippés avec un warning console.

Le contrat actuel est 1.3.0. Les changements breaking bumpent le major ; les nouveaux champs optionnels bumpent le minor. Les bundles compilés contre 1.x continuent de fonctionner tant que l'admin advertise MIN <= 1.x <= CURRENT.

pluginApi

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

Expose :

Méthode	Description
`addFilter<T>(hook, fn, priority?)`	Enregistre un handler de filtre. `fn(value, ...args) => value`. Priorité par défaut `100` ; plus basse en premier.
`addAction(hook, fn, priority?)`	Enregistre un handler d'action. `fn(...args) => void \| Promise<void>`.
`applyFilters<T>(hook, value, ...args) => Promise<T>`	Lance tous les filtres async pour le hook dans l'ordre des priorités, threadant la valeur.
`applyFiltersSync<T>(hook, value, ...args) => T`	Idem en sync (pour `page.head.extra`, `page.body.end`).
`doAction(hook, ...args) => Promise<void>`	Lance toutes les actions pour le hook.
`registerBlock(manifest)`	Enregistre un bloc d'éditeur Tiptap.
`registerDashboardCard(manifest)`	Enregistre une carte de tableau de bord.
`registerRegenerationTarget(manifest)`	Ajoute une entrée au menu Regenerate.
`registerInspectorTab(manifest)`	Ajoute un onglet à l'Inspecteur de l'éditeur.
`registerTermEditorSection(manifest)`	Ajoute une section pliable à la liste des Termes.
`registerEditorVariantProvider(manifest)`	Rend une bande d'onglets au-dessus de l'éditeur (multilang).

Hooks et contexts React

Export	Description
`useCmsData()`	Retourne `{ settings, posts, pages, terms, categories, tags, media, externalsLoaded }`. Live via souscription au backend actif.
`useAuth()`	Retourne `{ user, record, role, isAdmin, disabled, loading }`.
`useAllPosts(type)`	Retourne tous les posts / pages — live en mode `global`, snapshot one-shot en mode `paginated`.

Helpers de slug et URL

Export	Description
`slugify(input)`	Normalise un titre arbitraire vers un slug valide (`[a-z0-9-]+`).
`isValidSlug(slug)`	Validateur.
`findAvailableSlug(candidate, existing, ignoreId?)`	Ajoute `-2`, `-3`, etc. jusqu'à trouver un slug libre.
`buildPostUrl({ post, primaryTerm })`	URL relative d'un post : `<categorie>/<slug>.html` ou `<slug>.html`.
`buildTermUrl(term)`	URL relative d'une archive de catégorie : `<slug>/index.html`.
`pathToPublicUrl(baseUrl, path)`	Concatène `baseUrl` + `/` + `path` proprement (gère les slashes).
`canonicalPath(path)`	Retire `/index.html` en fin pour la forme canonique.
`canonicalUrl(baseUrl, path)`	Combine les deux pour produire l'URL canonique absolue.
`detectPathCollision(candidate, allPosts, ignoreId?)`	Détecte si une URL est déjà prise.
`detectTermSlugCollision(candidate, allTerms, ignoreId?)`	Détecte si un slug de terme est déjà pris.
`normalizeMediaSlug(slug)`	Ajoute un suffixe hex 6 caractères.
`postSortMillis(post)`	Date pour le tri de listing : publishedAt → updatedAt → createdAt → maintenant.

Helpers de média

Export	Description
`mediaToView(media)`	Convertit un `Media` brut en `MediaView` consommable par les thèmes.
`pickFormat(media, formatName)`	Pick une variante par nom, avec fallback vers `defaultFormat` puis la plus grande disponible.
`pickMediaUrl(media, formatName)`	Idem mais retourne juste l'URL.

Helpers markdown

Export	Description
`renderMarkdown(markdown)`	`marked` + DOMPurify. Retourne du HTML sûr.
`markdownToPlainText(markdown, maxLength?)`	Pour les excerpts, descriptions.

API Files de Flexweg

Export	Description
`uploadFile({ path, content })`	POST sur l'API Files.
`deleteFile(path)`	DELETE. 404 silencieux.
`deleteFolder(path)`	DELETE récursif.
`renameFile(from, to)`	MOVE.
`renameFolder(from, to)`	Idem pour les dossiers.
`createFolder(path)`	MKDIR.
`getFile(path)`	GET le contenu.
`listFiles(path)`	LIST les enfants.
`publicUrlFor(path)`	Combine baseUrl + path.
`fileToBase64(file)`	Helper pour le upload de blobs.
`getStorageLimits()`	Retourne `{ used, limit }`.
`FlexwegApiError`	Classe d'erreur custom.

CRUD backend (dispatchers)

Ces exports routent vers Firebase ou SQLite selon le backend actif. Le code consommateur est totalement agnostique du backend.

Export	Description
`fetchAllPosts({ type })`	Fetch tous les posts / pages, cache 30 s.
`createPost(post)`	Crée un post.
`updatePost(id, patch)`	Patch un post.
`uploadMedia(file, metadata)`	Upload + processing image.
`createTerm(term)`	Crée une catégorie / tag.
`buildAuthorLookup(users)`	Construit une map id→nom d'affichage.

Publisher

Export	Description
`publishPost(post, ctx)`	Rend + upload + cascade.
`buildPublishContext({ refreshTerms? })`	Charge tout en parallèle.
`buildSiteContext(ctx)`	Construit le `SiteContext` (settings, menus résolus, themeConfig).
`publishMenuJson(settings, posts, pages, terms)`	Re-upload `/menu.json`.
`renderHome(ctx, opts?)`	Rend la home avec le thème actif (utilisé par les plugins multilang).
`renderPageToHtml({ base, baseProps, template, templateProps })`	Rend un template en HTML chaîne.

Réglages

Export	Description
`updatePluginConfig(pluginId, config)`	Merge dans `settings.pluginConfigs[pluginId]`.
`updateThemeConfig(themeId, config)`	Merge dans `settings.themeConfigs[themeId]`.

i18n

Export	Description
`i18n`	L'instance i18next.
`pickPublicLocale(language)`	Pour `Intl.DateTimeFormat`.
`setActiveLocale(code)`	Change la langue admin.

UI primitives

Export	Description
`EntityCombobox`	Combobox avec recherche + select. Props : `options`, `value`, `onSelect`, `placeholder`.
`FontSelect`	Sélecteur de police Google Fonts.
`MediaPicker`	Picker de média avec uploader inline.

Helpers lib

Export	Description
`toast`	Module d'events pour toast. `toast.success(msg)`, `toast.error(msg)`.
`sha256Hex(str)`	Hashing.
`formatDateTime(timestamp, locale?)`	Affichage date+heure.
`cn(...classes)`	classnames helper (alias de `clsx`).

Support thème

Export	Description
`getActiveTheme(themeId)`	Retourne le manifest du thème actif.
`getCurrentPublishContext()`	Retourne le ctx courant pendant le rendu (utile dans `renderHtml` de blocs).
`logoPath(themeId, updatedAt?)`	URL du logo theme-assets avec cache-bust.
`uploadThemeLogo(themeId, file)`	Process + upload du logo.
`removeThemeLogo(themeId)`	Suppression.

SocialIcon

SocialIcon({ platform, className? }) rend l'icône SVG pour : twitter, github, linkedin, youtube, vimeo, facebook, instagram, mastodon, bluesky, threads, tiktok, dribbble, behance, pinterest, rss, email.

socialLabel(platform) retourne le label localisé.