Aller au contenu
Widgets

Fonctionnement du widget : architecture, commandes et déploiement

En bref
Pour qui
Développeurs qui reprennent, font évoluer ou déploient le widget.
Lecture
8 min
Mise à jour
12 novembre 2026

Le dossier widget/, les routes, le script d'intégration, le moteur de calcul, le contrat des partenaires, les tests et le déploiement.

Données utilisées

Le jeu embarqué de Plutôt là (packages/data/generated/), lu par le moteur du widget dans le navigateur.

Vue d'ensemble

widget/ est une application Vite et React du monorepo (@flux/widget-app), à côté de app/ (Plutôt là). C'est une coquille : son code vit dans deux paquets, @flux/widget (packages/widget/ : moteur, composant, script d'intégration, sans Mantine) et @flux/widget-editeur (packages/widget-editeur/ : les écrans du site et routesWidget). Elle a deux entrées :

  1. l'application (index.html) : l'accueil, l'éditeur, les pages des partenaires et la liste des exemples ;
  2. le script d'intégration (widget/src/embed.ts, qui réexporte @flux/widget/embed, soit packages/widget/src/embed/index.ts), publié à une adresse stable, /embed/plutot-la-widget.js, que les offices collent dans leurs pages.

Les deux affichent le même composant WidgetPlutotLa (packages/widget/src/widget/), nourri par le même moteur (packages/widget/src/moteur/).

Diagramme

Source : widget/vite.config.ts, widget/src/App.tsx, packages/widget/

Comment lire

Les deux entrées (l'application et le script d'intégration) affichent le même composant, qui demande ses chiffres au moteur, lequel s'appuie sur les paquets partagés avec Plutôt là. Seule l'application lit et écrit le stockage du navigateur.

Les routes de l'application

RouteÉcranFichier
/Accueil : ce qu'est le widget, les partenaires, les exemplespackages/widget-editeur/src/pages/Accueil.tsx
/editor, /editor/:slugÉditeur des partenaires (Thème, Contenu, Intégration)packages/widget-editeur/src/editor/
/examplesListe des pages d'exemple (fichiers statiques widget/public/examples/)packages/widget-editeur/src/pages/Exemples.tsx
/:slugPage d'un partenaire, à ses couleurs : sa variante choisie, les trois variantes et son codepackages/widget-editeur/src/pages/PagePartenaire.tsx
/:slug d'un partenaire inconnuPage introuvable, avec le bouton « Créer ce partenaire dans l'éditeur » (qui ouvre /editor/:slug quand l'adresse a la forme d'un identifiant)packages/widget-editeur/src/pages/PageIntrouvable.tsx

Source : widget/src/App.tsx, packages/widget-editeur/src/routes.tsx

Comment lire

Le routage se fait par chemin (React Router, createBrowserRouter), sans dièse : widget/vercel.json renvoie toute adresse inconnue vers index.html, sauf /embed/, /assets/ et /examples/.

L'accueil de l'application du widget, sur fond blanc : logo « Plutôt là widget », menu Éditeur, Exemples, Documentation ; « Pour les offices de tourisme et les sites », titre « Le widget Plutôt là » et trois phrases (deux lignes de code, ce que voit le visiteur, sans API ni compte) ; le bouton plein « Créer mon widget » et le bouton à contour « Voir les exemples » ; l'Éclaireur au chapeau ; puis « Aperçu en direct » avec le choix « Jour chargé » (choisi) ou « Aujourd'hui », la liste de ce que montre le widget (d'abord le verdict, les sept prochains jours, la courbe de la journée, des coins plus calmes, un lien vers l'application) et la carte du lac de Paladru : « Très fréquenté », les 7 jours, les barres heure par heure, « Plus calme à côté »

Source : packages/widget-editeur/src/pages/Accueil.tsx, capture du 12 novembre 2026

Comment lire

La promesse en trois phrases, les deux chemins (l'éditeur en bouton plein, les exemples en bouton à contour) et un aperçu vivant du partenaire plutot-la. Plus bas, hors de la capture : les partenaires et « Comment ça marche ». Le lien « Documentation » mène à cet onglet du portail.

Le script d'intégration

Fichier de packages/widget/src/embed/Rôle
index.tsL'entrée du build : définit l'élément plutot-la-widget (constante ELEMENT_WIDGET), une seule fois même si le script est chargé deux fois
element.tsxL'élément personnalisé : il ouvre un Shadow DOM, y monte React et suit ses attributs, son script JSON enfant et, sur la même adresse que l'éditeur, le stockage du navigateur
resolution.tsL'ordre de résolution de la configuration (attribut config, script JSON, stockage, partenaires livrés, défaut), puis les attributs lieu, variante, disposition, alternatives, langue ; l'ancien attribut mode n'est plus lu
base64url.tsL'encodage de l'attribut config : JSON de la configuration, en UTF-8, en base64url
format.tsLe format 3 de la configuration (ConfigurationWidget) et sa lecture, versions 1 à 3 comprises (lireConfiguration)
migration.tsL'écriture au format 3 (versConfiguration) et la conversion d'une ancienne configuration (migrerConfiguration), pour l'éditeur et le code à copier
snippet.tscodeIntegration(partenaire, { origine, avecConfig }) : le code à copier, utilisé par l'éditeur et la page du partenaire ; au-delà de 50 Ko, le logo et l'icône sont retirés
styles.tsLes styles du widget, injectés dans chaque Shadow DOM
Embed.module.cssLa remise à zéro dans le Shadow DOM (:host, casse, interligne, taille de base de 16 px)
polices.tsLes polices Fredoka et Nunito (paquets @fontsource-variable), déclarées dans la page hôte si le thème les demande
preambule-dev.tsDéveloppement seulement : pose le « préambule » du rechargement à chaud de React, absent des pages statiques /examples/, pour que le widget s'y affiche avec pnpm dev:widget ; vide dans le build
RenduEmbed.tsxLe rendu : calcule le résumé du lieu, le refait toutes les 10 minutes, affiche WidgetPlutotLa

Source : packages/widget/src/embed/

Comment lire

Dans l'ordre où ils interviennent. Le comportement vu par l'office (attributs, ordre de résolution) est décrit dans le tutoriel.

  • Shadow DOM : chaque widget est dessiné dans un sous-arbre isolé (mode ouvert). La feuille de style de la page hôte ne l'atteint pas, et les styles du widget ne débordent pas sur la page. :host { all: initial; display: block } puis la racine interne remettent à zéro les propriétés héritées (casse, interligne, espacement des lettres, alignement) ; seules la police (réglage « Police du site ») et la couleur du texte passent. La page hôte garde la main sur la boîte de l'élément (marge, largeur).
  • Les styles : ce sont les mêmes fichiers *.module.css que dans l'application. Chacun est aussi importé en texte (?inline de Vite, mêmes noms de classes), puis posé dans chaque Shadow DOM par une feuille construite partagée (adoptedStyleSheets), ou par une balise de style sur les navigateurs anciens. En développement, verifierClasses() avertit si une classe manque. Les couleurs du partenaire arrivent par des variables CSS posées sur la racine du widget.
  • Les polices : une police déclarée dans un Shadow DOM n'est pas prise en compte par les navigateurs. Si le thème demande Fredoka ou Nunito, le script ajoute donc une fois, dans l'en-tête de la page hôte, les déclarations @font-face (latin et latin étendu), qui pointent vers les fichiers servis par l'adresse du widget.
  • Sans Mantine : le composant WidgetPlutotLa n'utilise pas la bibliothèque de composants de l'application, pour garder le script léger et indépendant du site hôte.
  • Sans animation ni mascotte : les moments vivants de l'application (Éclaireur qui réagit, jauge qui se remplit, tampon) ne viennent pas dans le widget, par décision du 12 novembre 2026. Il reste une information sobre, posée à plat dans la page du partenaire.
  • Chargement en deux temps : le script lui-même est léger (dist/embed/plutot-la-widget.js : 32 684 octets, environ 7,8 Ko compressés, build du 12 novembre 2026 ; budget de 36 864 octets, soit 36 Ko, contrôlé après chaque build par scripts/check-embed.mjs ; relevé de 32 à 36 Ko le 12 novembre 2026, quand il ne restait que 84 octets de marge : de la place pour une correction, pas pour un nouvel import) ; le calcul (packages/widget/src/moteur/calcul.ts, qui tire @flux/core) et le jeu de données (prechargerJeu() de @flux/data/leger) arrivent par import dynamique, une seule fois pour tous les widgets de la page (packages/widget/src/moteur/charger.ts).
  • Tailles : les feuilles du widget n'emploient jamais rem seul, qui suit la taille de texte de la page hôte (souvent 10 px). Toutes les longueurs passent par calc(N * var(--pl-w-rem, 1rem)) ; le script d'intégration fixe --pl-w-rem: 16px, l'application la laisse à 1rem. Vérifié sur une page hôte réglée à html { font-size: 10px } : le widget garde sa taille.
  • Mise à jour en direct : l'élément suit ses attributs (observedAttributes), son script JSON enfant (un MutationObserver) et, sur la même adresse que l'éditeur, le stockage du navigateur (événement storage) ; plusieurs changements à la suite donnent un seul rendu.
  • Diagnostic : l'élément porte l'attribut data-config (attribut, script, stockage, integre ou defaut) ; dans le Shadow DOM, la racine du widget porte data-variante, data-etat (chargement, pret, erreur) et lang (plus de data-sombre : le widget est toujours clair). Toute valeur ignorée donne un avertissement [plutot-la-widget] dans la console, jamais une exception chez le partenaire.

Le moteur

chargerResume(lieuId, date?) (packages/widget/src/moteur/index.ts) rend un ResumeLieu, ou une ErreurMoteur (lieu-inconnu, donnees-indisponibles) que le widget affiche en clair :

Champ de ResumeLieuContenu
maintenantL'heure et le niveau prévu maintenant (ou à l'ouverture, hors de 8 h à 20 h)
journeeLe niveau et un indice de 0 à 1 000 (déduit) pour chaque heure de 8 h à 20 h
meilleurMomentLe créneau le plus calme de la journée, le plus tôt à égalité
semaineLes 7 prochains jours : niveau du pic, jour férié, vacances
alternativesLes lieux plus calmes à proximité : nom, commune, distance, niveau au même moment, raison
fiabilite, sourcesUne phrase sur la fiabilité et les fichiers sources

Itinéraire du jour (bloc facultatif, contenu.itineraire) : useItineraire (packages/widget/src/moteur/itineraire.ts) charge à la demande les sorties embarquées de Plutôt là et en choisit une (itineraireDuLieu, itineraire-choix.ts). Seules les sorties au récit relu et validé comptent ; la sortie doit passer par le lieu suivi (une de ses étapes est une fiche de ce lieu). À plusieurs, le widget préfère une sortie d'un seul jour, puis la saison la plus proche de la date regardée, puis l'ordre des identifiants : le choix est stable. Il rend le titre, la durée, le nombre d'étapes et le lien vers le récit dans l'application (#/itineraires/<identifiant>). Bloc non activé : rien n'est chargé, et le premier fichier du script d'intégration ne grossit pas.

Source : packages/widget/src/moteur/types.ts · (déduit)

Comment lire

Le calcul réutilise la logique de Plutôt là (@flux/core) et son jeu de données embarqué (@flux/data), chargé à la demande. Détail des méthodes : l'onglet Matching, et Algorithmes et Données de l'onglet Plutôt là.

Le contrat des partenaires

Un partenaire (Partenaire, packages/core/src/partenaires/types.ts, entrée @flux/core/partenaires) est un objet JSON. Ce que l'éditeur écrit (attribut config, fichier téléchargé) suit la version 3 du format (ConfigurationWidget, packages/widget/src/embed/format.ts) ; une version 1 ou 2 est encore lue et convertie (migrerConfiguration) :

  • slug (identifiant d'adresse), nom, siteWeb, logo et icone (images en data URL) ;
  • theme : 13 couleurs, rayons, polices, graisse des titres, bordure. La version 3 n'a plus mode, couleursSombre ni ombre : dans un code plus ancien, ils sont ignorés (le widget est toujours clair, sans ombre) ;
  • contenu (ContenuWidget) : lieu, variante, disposition, titre, message, éléments affichés, lieux alternatifs (quand, combien, pourquoi), bouton, langue, et itineraire (facultatif). Un code copié avant ce réglage n'a pas le champ : son widget ne change pas.

themeEnVariables(theme) transforme le thème en variables CSS posées sur la racine du widget : --pl-w-primaire, --pl-w-texte, --pl-w-carte… (une par couleur), --pl-w-rayon-conteneur, --pl-w-rayon-carte, --pl-w-rayon-bouton, --pl-w-police-titres, --pl-w-police-texte, --pl-w-graisse-titres, --pl-w-bordure (plus de --pl-w-ombre : le widget n'a plus d'ombre). Les feuilles *.module.css du widget n'utilisent que ces variables : aucune couleur n'est écrite dans le code, sauf les préréglages de packages/core/src/partenaires/presets.ts.

Le stockage (packages/stockage/src/partenaires.ts, entrée @flux/stockage/partenaires) garde les partenaires dans le localStorage, clé plutot-la-widget:partenaires:v1, et prévient les autres onglets à chaque changement. Les partenaires livrés avec l'application (plutot-la et cinq partenaires de démonstration : alpes-isere, chartreuse, grenoble-alpes-tourisme, pays-voironnais, societe-lac-paladru) sont toujours disponibles ; une version enregistrée les remplace.

Commandes

Depuis la racine du dépôt (pnpm 12.15) :

TerminalBash
npx --yes pnpm@12.15.0 install # une fois pnpm dev:widget # application sur http://localhost:5176 (/editor, /examples…) pnpm --filter @flux/widget-app build # vérification des types, puis dist/ (application + dist/embed/plutot-la-widget.js) pnpm --filter @flux/widget-app typecheck # types de l'application ; --filter @flux/widget pour le paquet d'intégration pnpm exec vitest run packages/widget packages/widget-editeur # tests du widget et de son site node scripts/check-styles.mjs --strict # CSS séparé, et design simplifié : aucune ombre hors élément flottant, aucun mode sombre pnpm check # biome, CSS séparé, couches des paquets et types de tout le monorepo

En développement, /embed/plutot-la-widget.js est servi directement par la source (widget/src/embed.ts, extension de vite.config.ts) : les pages /examples/… marchent aussi avec pnpm dev:widget. Le port 3003 est réservé au portail : ne pas y lancer le widget.

Déploiement sur Vercel

Un projet Vercel à part, sur le même dépôt, comme l'application Plutôt là :

Réglage du projetValeur
Root Directorywidget
Include source files outside of the Root Directoryactivé (le widget importe packages/*)
Framework PresetVite (repris de widget/vercel.json)
Commandescelles de widget/vercel.json : installation pnpm 12.15 figée, pnpm run build, sortie dist
Variables d'environnementaucune

Source : widget/vercel.json

Comment lire

Rien à saisir à la main en dehors du Root Directory et de l'option des fichiers hors du dossier : le reste est dans widget/vercel.json.

widget/vercel.json règle aussi les en-têtes :

  • /embed/… : Access-Control-Allow-Origin: * (tout site peut charger le script en module) et un cache court de 5 minutes, pour que les offices reçoivent vite les nouvelles versions ;
  • /assets/… : même autorisation, cache d'un an (les noms de fichiers changent à chaque version) ;
  • /examples/… : X-Robots-Tag: noindex, nofollow, pour que les copies de pages d'offices ne soient pas indexées ;
  • partout : X-Content-Type-Options: nosniff et Referrer-Policy: strict-origin-when-cross-origin.

Un push sur main déclenche le déploiement : il se fait seulement à la demande de l'équipe.

Limites

À garder en tête

  • Le widget charge le jeu de données complet de Plutôt là (1,8 Mo, environ 300 Ko compressés, mesurés sur le build du 10 novembre 2026), même pour un badge d'une ligne. Des fichiers de prévisions précalculés par lieu (proposition /donnees/v1/lieux/… de la page Intégration et écosystème) l'allégeraient.
  • La police et la couleur du texte de la page hôte traversent le Shadow DOM (voulu pour « Police du site ») ; le reste est remis à zéro, mais un site qui pose des styles très particuliers sur l'élément lui-même (plutot-la-widget { … }) peut encore en changer la boîte. Les déclarations des polices Fredoka et Nunito sont posées dans l'en-tête de la page hôte : sous une politique de sécurité stricte, elles demandent style-src 'unsafe-inline' (voir le tutoriel).
  • Pas de version dans l'adresse du script (/embed/plutot-la-widget.js) : un changement incompatible du format des partenaires toucherait tous les sites. Le champ version du format sert à le détecter.
Toutes les limites (4)
  • Aucun serveur : pas de signalement en direct, pas de statistiques d'usage, pas de partage des réglages entre personnes.