Fonctionnement du widget : architecture, commandes et déploiement
Vue d'ensemble
widget/ est une application Vite et React du monorepo (@flux/), à côté de app/ (Plutôt là). C'est une coquille : son code vit dans deux paquets, @flux/widget (packages/ : moteur, composant, script d'intégration, sans Mantine) et @flux/ (packages/ : les écrans du site et routesWidget). Elle a deux entrées :
- l'application (
index.html) : l'accueil, l'éditeur, les pages des partenaires et la liste des exemples ; - le script d'intégration (
widget/, qui réexportesrc/ embed. ts @flux/, soitwidget/ embed packages/), publié à une adresse stable,widget/ src/ embed/ index. ts /embed/, que les offices collent dans leurs pages.plutot- la- widget. js
Les deux affichent le même composant WidgetPlutotLa (packages/), nourri par le même moteur (packages/).
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 | Écran | Fichier |
|---|---|---|
/ | Accueil : ce qu'est le widget, les partenaires, les exemples | packages/ |
/editor, /editor/: | Éditeur des partenaires (Thème, Contenu, Intégration) | packages/ |
/examples | Liste des pages d'exemple (fichiers statiques widget/) | packages/ |
/:slug | Page d'un partenaire, à ses couleurs : sa variante choisie, les trois variantes et son code | packages/ |
/:slug d'un partenaire inconnu | Page introuvable, avec le bouton « Créer ce partenaire dans l'éditeur » (qui ouvre /editor/: quand l'adresse a la forme d'un identifiant) | packages/ |
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/ renvoie toute adresse inconnue vers index.html, sauf /embed/, /assets/ et /examples/.

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/ | Rôle |
|---|---|
index.ts | L'entrée du build : définit l'élément plutot- (constante ELEMENT_), une seule fois même si le script est chargé deux fois |
element.tsx | L'é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. | L'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.ts | L'encodage de l'attribut config : JSON de la configuration, en UTF-8, en base64url |
format.ts | Le format 3 de la configuration (ConfigurationWidget) et sa lecture, versions 1 à 3 comprises (lireConfiguration) |
migration.ts | L'écriture au format 3 (versConfiguration) et la conversion d'une ancienne configuration (migrerConfiguration), pour l'éditeur et le code à copier |
snippet.ts | codeIntegration(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.ts | Les styles du widget, injectés dans chaque Shadow DOM |
Embed. | La remise à zéro dans le Shadow DOM (:host, casse, interligne, taille de base de 16 px) |
polices.ts | Les polices Fredoka et Nunito (paquets @fontsource-), déclarées dans la page hôte si le thème les demande |
preambule- | Dé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: ; vide dans le build |
RenduEmbed. | Le 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: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).initial; display: block } - Les styles : ce sont les mêmes fichiers
*.module.cssque dans l'application. Chacun est aussi importé en texte (?inlinede 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
WidgetPlutotLan'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/: 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 parembed/ plutot- la- widget. js scripts/; 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 (check- embed. mjs packages/, qui tirewidget/ src/ moteur/ calcul. ts @flux/core) et le jeu de données (prechargerJeu()de@flux/) arrivent par import dynamique, une seule fois pour tous les widgets de la page (data/ leger packages/).widget/ src/ moteur/ charger. ts - Tailles : les feuilles du widget n'emploient jamais
remseul, qui suit la taille de texte de la page hôte (souvent 10 px). Toutes les longueurs passent parcalc(N * var(--; le script d'intégration fixepl- w- rem, 1rem)) --pl-, l'application la laisse àw- rem: 16px 1rem. Vérifié sur une page hôte réglée àhtml { font-: le widget garde sa taille.size: 10px } - Mise à jour en direct : l'élément suit ses attributs (
observedAttributes), son script JSON enfant (unMutationObserver) et, sur la même adresse que l'éditeur, le stockage du navigateur (événementstorage) ; plusieurs changements à la suite donnent un seul rendu. - Diagnostic : l'élément porte l'attribut
data-config(attribut,script,stockage,integreoudefaut) ; dans le Shadow DOM, la racine du widget portedata-,variante data-etat(chargement,pret,erreur) etlang(plus dedata-sombre: le widget est toujours clair). Toute valeur ignorée donne un avertissement[plutot-dans la console, jamais une exception chez le partenaire.la- widget]
Le moteur
chargerResume(lieuId, date? (packages/) rend un ResumeLieu, ou une ErreurMoteur (lieu-inconnu, donnees-) que le widget affiche en clair :
Champ de ResumeLieu | Contenu |
|---|---|
maintenant | L'heure et le niveau prévu maintenant (ou à l'ouverture, hors de 8 h à 20 h) |
journee | Le niveau et un indice de 0 à 1 000 (déduit) pour chaque heure de 8 h à 20 h |
meilleurMoment | Le créneau le plus calme de la journée, le plus tôt à égalité |
semaine | Les 7 prochains jours : niveau du pic, jour férié, vacances |
alternatives | Les lieux plus calmes à proximité : nom, commune, distance, niveau au même moment, raison |
fiabilite, sources | Une phrase sur la fiabilité et les fichiers sources |
Itinéraire du jour (bloc facultatif, contenu.) : useItineraire (packages/) charge à la demande les sorties embarquées de Plutôt là et en choisit une (itineraireDuLieu, itineraire-). 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/). 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/, entrée @flux/) est un objet JSON. Ce que l'éditeur écrit (attribut config, fichier téléchargé) suit la version 3 du format (ConfigurationWidget, packages/) ; une version 1 ou 2 est encore lue et convertie (migrerConfiguration) :
slug(identifiant d'adresse),nom,siteWeb,logoeticone(images en data URL) ;theme: 13 couleurs, rayons, polices, graisse des titres, bordure. La version 3 n'a plusmode,couleursSombreniombre: 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, etitineraire(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-, --pl-w-texte, --pl-w-carte… (une par couleur), --pl-, --pl-, --pl-, --pl-, --pl-, --pl-, --pl- (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/.
Le stockage (packages/, entrée @flux/) garde les partenaires dans le localStorage, clé plutot-, 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-, pays-, societe-) sont toujours disponibles ; une version enregistrée les remplace.
Commandes
Depuis la racine du dépôt (pnpm 12.15) :
Bash
En développement, /embed/ est servi directement par la source (widget/, extension de vite.) : les pages /examples/… marchent aussi avec pnpm dev:. 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 projet | Valeur |
|---|---|
| Root Directory | widget |
| Include source files outside of the Root Directory | activé (le widget importe packages/*) |
| Framework Preset | Vite (repris de widget/) |
| Commandes | celles de widget/ : installation pnpm 12.15 figée, pnpm run build, sortie dist |
| Variables d'environnement | aucune |
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/.
widget/ règle aussi les en-têtes :
/embed/…:Access-(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 ;Control- Allow- Origin: * /assets/…: même autorisation, cache d'un an (les noms de fichiers changent à chaque version) ;/examples/…:X-, pour que les copies de pages d'offices ne soient pas indexées ;Robots- Tag: noindex, nofollow - partout :
X-etContent- Type- Options: nosniff 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/de la page Intégration et écosystème) l'allégeraient.v1/ lieux/ … - 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-) 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 demandentla- widget { … } style-(voir le tutoriel).src 'unsafe- inline' - Pas de version dans l'adresse du script (
/embed/) : un changement incompatible du format des partenaires toucherait tous les sites. Le champplutot- la- widget. js versiondu 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.