Chez Premier Octet, nous suivons cette évolution de près. En octobre 2023, nous décryptions déjà la V1 de Medusa dans un premier article sur notre blog. Trois ans plus tard, les annonces de ce printemps/été 2026 confirment cette tendance : l'avenir appartient aux architectures modulaires et nativement pensées pour le développement assisté par IA. C'est donc l'occasion d'un nouvel article pour faire le tour de ces nouveautés qui redéfinissent notre façon de concevoir l'e-commerce.

1. L'ingénierie « Agentic » : quand l'IA s'intègre au workflow de développement

La force de Medusa, c'est d'accompagner un changement de paradigme fondamental du secteur de l'e-commerce. Là où le marché s'est longtemps standardisé autour de templates et de sites clés en main pour simplifier les lancements, la tendance actuelle exige une personnalisation absolue, désormais accompagnée par l'IA.

C'est tout l'objet de l'AI Toolbox de Medusa : un écosystème d'outils qui cadre et sécurise l'intervention des agents pour leur permettre de bâtir des fonctionnalités sur mesure en un simple prompt.

Agent Skills Library : cadrer l'IA avec l'expertise native de Medusa

Pour guider efficacement les agents et éviter qu'ils ne dévient des standards du framework, Medusa fournit sa propre bibliothèque de skills. Pour l'ajouter à votre projet, il suffit d'exécuter :

npx skills add medusajs/medusa-agent-skills

Trois grandes familles de compétences sont disponibles dans le contexte de votre agent :

• Admin & Dashboard (building-with-medusa, building-admin-dashboard-customizations) : fournit les connaissances fondamentales de l'architecture Medusa pour créer des features e-commerce personnalisées (wishlist, intégration de services externes…) et étendre l'UI de l'admin.
• Storefront & UX (building-storefronts, storefront-best-practices) : rassemble les bonnes pratiques e-commerce (SEO, UX) pour bâtir votre boutique indépendamment du framework choisi (Next.js, Vite).
• Store Operations & Automatisation (creating-internal-agents) : permet de configurer des agents autonomes dédiés à la gestion quotidienne de votre site (audit automatique des stocks, support client personnalisé).

Un plugin et un tutoriel interactif sur Claude Code

Medusa s'intègre directement dans le CLI d'Anthropic via deux extensions spécifiques : si medusa-dev sert à générer des fonctionnalités à la volée, le framework se démarque surtout par un onboarding interactif inédit avec learn-medusa@medusa. En tapant la commande /learn-medusa:learning-medusa ou le prompt « I want to learn Medusa », l'IA se transforme en mentor et vous guide pas à pas dans un cas pratique réel.

# Démarrez Claude Code et ajoutez le dépôt Medusa
claude
/plugin marketplace add medusajs/medusa-claude-plugins

# Features
/plugin install medusa-dev@medusa

# Tutoriel
/plugin install learn-medusa@medusa

Un plugin ESLint adapté à Medusa

Les linters classiques ignorent les conventions de Medusa. Résultat : un code TypeScript valide peut quand même crasher au runtime (ex: données non sérialisables, mauvais nommage de route). C'est là qu'intervient @medusajs/eslint-plugin. Si le code écrit est non conforme, le linter lève une erreur claire, fini le debug fastidieux dans les logs. Le plugin est inclus par défaut depuis la v2.16.0, et embarque trois presets : recommended (standard), strict (typé) et modules (packages).

2. Nouvelles fonctionnalités et plugins au service du sur-mesure

L'offre open-source de Medusa s'étoffe avec l'arrivée de nouvelles fonctionnalités et plugins majeurs.

Global Product Options et Multi-shipping : la fin des limites du catalogue

La mise à jour de juin 2026 apporte l'une des fonctionnalités les plus réclamées par la communauté : les Global Product Options. Il est désormais possible de créer des options réutilisables, de centraliser leurs valeurs et de permettre aux utilisateurs de filtrer les produits par attributs communs directement sur le storefront.

Côté checkout, le framework repousse encore les limites avec la prise en charge des paniers Multi-shipping. Une commande peut désormais inclure plusieurs méthodes d'expédition réparties sur différents profils de livraison.

Loyalty Plugin : la fidélisation passe au 100 % open-source

Initialement réservé aux utilisateurs de Medusa Cloud, le Loyalty Plugin fait son entrée dans la version open-source standard (v2.14.0). Divisé en deux modules autonomes (Loyalty et Store Credit), cet outil offre aux marchands une gestion centralisée des cartes cadeaux et crédits d'achat. Fini les abonnements coûteux à des SaaS tiers. Les développeurs disposent désormais de briques natives pour coder des portefeuilles virtuels (wallets), des systèmes de cashback ou des programmes VIP à plusieurs niveaux, avec une liberté totale sur la logique métier.

Shopify Sync : le plugin qui simplifie la transition depuis Shopify

L'engouement autour de Medusa comme alternative à Shopify se confirme avec le plugin @rx-ventures/medusa-plugin-shopify-sync. Conçu pour les migrations ou les architectures hybrides, cet outil automatise le rapatriement complet du catalogue (clients, produits, commandes, remises) de Shopify vers Medusa v2.

# 1. Installer le plugin Shopify Sync
yarn add @rx-ventures/medusa-plugin-shopify-sync

# 2. Générer la clé de chiffrement pour sécuriser le token Shopify
openssl rand -hex 32
# -> À copier dans le .env : SHOPIFY_SYNC_ENCRYPTION_KEY=...

# 3. Exécuter la migration pour créer les tables de suivi
yarn medusa db:migrate

Une fois le plugin configuré, tout se pilote depuis le tableau de bord Medusa :

• Configuration & synchronisation : liaison de la boutique via l'onglet dédié et import historique en un clic dans l'ordre recommandé (clients, produits, remises, puis commandes).
• Webhooks & logs : activation instantanée des routes en temps réel pour synchroniser les stocks et ventes, avec un écran de monitoring rafraîchi toutes les 5 secondes pour suivre l'activité.

Une sécurité renforcée : Authentification multifacteur (MFA)

Le module d'authentification de Medusa intègre désormais le MFA en natif. L'implémentation repose sur des fournisseurs configurables, notamment le support du TOTP pour les applications d'authentification (Google Authenticator, etc.). Cette approche modulaire permet de sécuriser les accès — en particulier pour les comptes administrateurs — tout en offrant un contrôle précis sur les flux de vérification et les politiques d'accès.

3. Infrastructure et production : la maturité de Medusa Cloud

L'un des grands avantages d'une architecture découplée avec Medusa réside dans la liberté de déploiement. Le framework reste une application Node.js standard, hébergeable sur l'infrastructure de votre choix (AWS, GCP, Railway, etc.), ce qui garantit une maîtrise totale des coûts d'hébergement.

Toutefois, pour les équipes qui souhaitent déléguer la partie DevOps sans subir les blocages des SaaS traditionnels, Medusa Cloud s'est doté d'outils plus matures pour la production. Sans être un passage obligé, la solution managée intègre désormais :

• Un accès direct à Postgres : l'ouverture de la base de données en écriture permet d'exécuter des scripts complexes ou de brancher des outils d'analytique en direct.

• Une télémétrie avancée : des dashboards natifs pour monitorer la latence des routes API et anticiper les pics de charge.

• Un CLI dédié : avec @medusajs/mcloud, le pilotage des environnements et le suivi des logs se font directement depuis le terminal.

Que l'on gère sa propre infrastructure ou que l'on opte pour leur cloud, le framework fournit désormais tous les outils pour gérer sereinement la mise en production et la montée en charge.

En conclusion

Dès 2023, Medusa apparaissait déjà à nos yeux comme une alternative prometteuse au monopole des solutions propriétaires. Trois ans plus tard, le framework a non seulement tenu ses promesses de flexibilité, mais il a pris une longueur d'avance décisive.

Les hausses de prix et les barrières techniques des plateformes SaaS ne sont plus une fatalité. Avec l'intégration de l'IA dans son workflow et un écosystème open-source toujours plus riche, Medusa confirme son statut d'alternative de choix face à Shopify. Le framework redonne le contrôle aux développeurs pour construire des architectures sur mesure, le tout sans la moindre commission sur les ventes.

Votre plateforme actuelle freine vos ambitions ? Chez Premier Octet, nous vous accompagnons dans la transition vers une architecture e-commerce performante, libre et scalable. Contactez-nous pour discuter de votre projet.

Ce billet déroule une petite expérience : une web app qui vous connecte avec Google, vous laisse choisir des fichiers dans votre Drive, les indexe avec Gemini, puis discute avec eux.

C'est quoi un RAG, vraiment ?

Retrieval-Augmented Generation, dans ce contexte c'est en fait deux étapes :

1. Récupérer — étant donné une question, trouver les passages de vos documents les plus susceptibles de contenir la réponse.
2. Générer — coller ces passages dans le prompt et laisser le LLM formuler la réponse.

Habituellement, nous avons besoin de : découper les documents en chunks, les transformer en vecteurs, stocker ces vecteurs dans une base, et classer les résultats à la requête. Chacune de ces étapes a son lot d'articles qui débattent de la « bonne » manière.

Le raccourci ici est de laisser Gemini tout faire. L'API Gemini expose un FileSearchStore — vous uploadez des fichiers, Google s'occupe du découpage, des embeddings et de la récupération. Au moment de la requête, vous passez le store comme un outil, et le modèle décide quand chercher et quoi faire des résultats.

Trois dépendances, un seul fournisseur

Toute la stack tient dans Google Workspace :

• API Gemini — le LLM et le File Search Store. Une clé API.
• OAuth Google — pour que l'utilisateur autorise l'app à lire son Drive. Un client OAuth.
• API Google Drive — pour lister et télécharger les fichiers. Le même client OAuth.

Pas de Pinecone, pas de LangChain, pas de modèle d'embedding à choisir. La seule « infrastructure » nécessaire est une mémoire pour savoir quels fichiers Drive ont été indexés et le nom du store.

Pour le framework j'ai choisi TanStack Start — un framework React full-stack où la logique serveur n'est qu'une fonction typée que le client appelle directement. Pas de routes REST à écrire, pas de frontière client/serveur à concevoir. Une server function ressemble à ça :

const chat = createServerFn({ method: 'POST' })
  .validator((d: { question: string }) => d)
  .handler(async ({ data }) => ask(data.question))

Et côté client :

await chat({ data: { question: '...' } })

C'est toute la couche RPC.

Étape 1 : chercher dans Drive

Une fois l'utilisateur connecté en OAuth (avec le scope drive.readonly), lister les fichiers tient en un appel :

const res = await drive.files.list({
  q: "trashed = false",
  pageSize: 50,
  fields: 'files(id, name, mimeType, modifiedTime)',
  orderBy: 'modifiedTime desc',
})

La seule subtilité, ce sont les types MIME. Les PDF et fichiers texte peuvent se télécharger tels quels (alt: 'media'), mais les Google Docs, Sheets et Slides sont virtuels — il faut les exporter d'abord :

const GOOGLE_DOC_EXPORTS = {
  'application/vnd.google-apps.document':     { mimeType: 'application/pdf' },
  'application/vnd.google-apps.presentation': { mimeType: 'application/pdf' },
  'application/vnd.google-apps.spreadsheet':  { mimeType: 'text/csv' },
}

Un Google Doc est exporté en PDF, un Sheet en CSV. Gemini File Search gère les deux nativement.

Étape 2 : indexer un fichier

Voilà la partie magique. Indexer, c'est uploader + attendre :

const ai = new GoogleGenAI({ apiKey })

// Crée le store une fois, à la première utilisation
const store = await ai.fileSearchStores.create({
  config: { displayName: 'gemini-rag' },
})

// Upload d'un d'un fichier Drive
let op = await ai.fileSearchStores.uploadToFileSearchStore({
  file: new Blob([bytes], { type: mimeType }),
  fileSearchStoreName: store.name,
  config: { displayName: name, mimeType },
})

// L'indexation est asynchrone
while (!op.done) {
  await new Promise(r => setTimeout(r, 2000))
  op = await ai.operations.get({ operation: op })
}

Voilà tout le pipeline d'indexation. Google découpe le fichier, calcule les embeddings et les écrit dans le store. En coulisses c'est la même mécanique qu'une base vectorielle — sauf que vous n'avez pas à l'opérer.

Le seul état qu'on garde nous-mêmes est un petit fichier JSON qui mappe { driveId → { name, mimeType } }. Il existe pour deux raisons : éviter de réindexer des fichiers déjà uploadés, et retenir le nom du store entre les redémarrages du serveur.

Étape 3 : discuter

const res = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: question,
  config: {
    tools: [{ fileSearch: { fileSearchStoreNames: [store.name] } }],
  },
})
return res.text

Voilà tout le handler de chat. On donne à Gemini la question et un pointeur vers le store. Gemini décide s'il faut chercher, exécute la récupération, choisit les chunks pertinents et écrit la réponse.

Si vous avez déjà construit un RAG à la main, c'est le moment qui ressemble à de la triche.

Ce que ce n'est pas

Soyons honnête, nous sommes assez éloigné d'un projet de production, cependant la logique principale du RAG est présente et fonctionnelle.

Une solution complète aurait besoin de :

• un stockage en base de donnée
• une synchronisation automatique et récursive des dossiers Drive
• une interface de tchat complète, multimodale et streamée (https://ai-sdk.dev/)

À retenir

Si vous construisez un RAG pour un outil interne et que vous êtes déjà dans l'écosystème Google, vous n'avez presque certainement pas besoin de monter une base vectorielle. À savoir que le free tier de l'API FileSearch permet un stockage de 1 GB.

Si vous cherchez à discuter avec vos documents avec de l'AI, aussi dans l'écosystème Google, je vous recommande chaudement NotebookLM qui permet en plus de générer du contenu (résumé audio, vidéo, quiz, infographie...) en rapport avec vos documents.

L'ensemble du code concernant le RAG tient sur ces 500 lignes de code et est disponible sur GitHub.

La promesse est la suivante : permettre à n'importe quel LLM d'interagir directement avec une instance Directus de manière conversationnelle.

Mais qu'est-ce que ce MCP apporte de plus par rapport à l'API Directus existante, déjà très complète ? Découverte de ce MCP en action.

Qu'est-ce que le MCP ?

Le Model Context Protocol (MCP) est une norme qui permet de standardiser la manière dont un LLM peut interagir avec une application. Il expose les capacités, les actions et les contraintes de cette dernière de façon lisible par un LLM, tout en respectant un cadre strict de permissions et de schéma. Nous avions déjà abordé ce sujet dans un article précédent : Guide pratique du Model Context Protocol : tout comprendre sur les tools et serveurs MCP.

Le MCP de Directus

Le serveur MCP de Directus expose ses capacités sous forme de tools, automatiquement découvrables par le LLM. Cela permet à n'importe quel LLM de lire des collections, modifier des schémas, gérer du contenu ou naviguer dans des relations complexes.

Dans ces tools on retrouve notamment :

• La gestion des collections et champs
• Le CRUD (Create, Read, Update, Delete) sur les items
• La manipulation des assets
• La lecture des permissions et rôles
• Certaines opérations avancées liées au schéma.

La liste complète est disponible dans la documentation officielle, mais un point mérite d'être souligné : 👉 rien ici n'est fondamentalement nouveau par rapport à l'API Directus existante.

La vraie valeur ajoutée du MCP réside dans l'interaction avec le LLM qui peut raisonner sur votre instance Directus en temps réel, orchestrer des migrations, etc.

Comment utiliser le MCP de Directus

Il existe une documentation très claire et explicite ainsi que des tutoriels vidéo sur le sujet mais globalement pour le setup vous aurez besoin de :

• Une instance de Directus >v11.2
• Un client AI (Cursor, Claude Desktop, Copilot, ChatGPT, etc.)
• Un (nouvel) utilisateur dans votre instance avec les permissions adéquates (ainsi que son token).

Une fois le serveur MCP configuré côté client IA, un premier test très simple consiste à poser une question ouverte sur l'instance : "Can you tell me about my Directus project?"

Si la configuration est correcte, le LLM est capable :

• d'interroger les collections
• de comprendre le schéma
• et de restituer une vue cohérente du projet.

Test du MCP

Pour tester le MCP dans un cas concret, j'ai ajouté une fonctionnalité de tags à un blog existant. L'objectif était double :

• créer un nouveau modèle tags
• analyser le contenu des articles déjà publiés afin d'y associer automatiquement un ou des tags pertinents.

Le test combine plusieurs dimensions : création de schéma, compréhension sémantique du contenu et écriture de relations existantes. Autrement dit, exactement le type de tâche que le MCP prétend simplifier.

Une petite minute plus tard, j'avais mon nouveau modèle ainsi que mes articles de blog mis à jour.

Use cases pertinents

Pour aller au-delà du simple effet démo, j'ai recherché et identifié quelques usages concrets du MCP qui pourraient peut-être convaincre les sceptiques.

Côté contenu

Le MCP permet surtout à des profils non techniques de gagner en autonomie. L'interface conversationnelle réduit fortement la courbe d'apprentissage de Directus et limite les allers-retours avec les équipes techniques, notamment lors de l'onboarding ou de tâches ponctuelles mais pénibles.

• Migration d'articles depuis Google Docs, Notion ou Markdown brut
• Renommage et restructuration d'assets média
• Reprise ou duplication de structures existantes
• Recherche conversationnelle dans un catalogue éditorial

“Retrouve-moi l'article qui parle du produit X publié l'année dernière, même si le titre exact ne contient pas le nom du produit.”

Côté développement

Pour les profils techniques, le MCP ne remplace pas les outils classiques, mais accélère les phases de réflexion et de prototypage. Il permet d'explorer un schéma, tester des hypothèses ou ajuster des modèles sans écrire de code ni maîtriser immédiatement l'existant.

• Prototypage rapide de nouveaux modèles.
• Exploration d'une base existante sans connaître son historique.
• Migration fastidieuse de données.

“Explique-moi comment sont liées les collections projects, clients et invoices, et dis-moi où se trouve la source de vérité pour le statut de facturation.”

Les usages sont très diversifiés, ce n'est pas un moteur d'automatisation, ni un remplaçant de l'API. Le MCP est surtout utile pour explorer, prototyper et intervenir ponctuellement sur une instance. Dans ces cas précis, il remplit bien sa promesse.

À noter que Directus n'est pas le seul CMS à explorer ce type d'intégration. D'autres CMS comme Strapi ou Sanity proposent également des intégrations basées sur le protocole MCP.

Dans cet article, je partage avec vous comment nous avons mis en place cet agent conversationnel et pourquoi nous avons choisi cette approche pour gérer une partie de la relation client.

Contexte

Photobooth AI est notre application qui permet de générer des photos personnalisées grâce à l'intelligence artificielle. Comme toute application SaaS, elle nécessite un support client efficace pour accompagner les utilisateurs dans leur découverte et utilisation de la plateforme.

Jusqu'à récemment, nous utilisions Crisp comme solution de chat support traditionnelle. Cette approche fonctionnait, mais elle présentait certaines limitations : disponibilité limitée aux heures ouvrables, répétition des mêmes questions de base, et charge importante sur notre équipe support pour des demandes souvent similaires.

Nous avons également observé que certains utilisateurs tentaient d'utiliser le chat support directement pour générer leurs images. Ils y téléchargeaient leurs photos et rédigeaient leurs prompts, s'attendant à pouvoir obtenir leurs créations via ce canal. Cette approche, bien que témoignant de leur envie d'interagir facilement avec notre service, était sans issue et pouvait se révéler frustrante.

C'est en partant de ce constat et fort de notre expertise en développement d'agents conversationnels que nous avons décidé de développer un assistant IA spécialement conçu pour Photobooth AI. L'objectif ? Optimiser notre support client tout en améliorant l'expérience utilisateur.

Un support automatisé et personnalisé : notre approche

L'objectif principal de cette intégration est de créer un support client automatisé et personnalisé spécifiquement adapté à notre plateforme. Contrairement à une solution générique, notre assistant IA est configuré avec :

• Le contenu complet de notre FAQ : Toutes les questions fréquentes et leurs réponses officielles
• Le plan du site (sitemap) : Pour guider efficacement les utilisateurs vers les bonnes sections
• Un prompt système spécialisé : Conçu spécifiquement pour les enjeux de Photobooth AI
• Un outil de feedback intégré : Qui transmet automatiquement les demandes complexes au support humain

Cette approche nous permet de maintenir la qualité du support tout en automatisant une grande partie des interactions client. En somme, un système qui connaît parfaitement notre produit et sait orienter nos utilisateurs.

Les avantages de cette approche

Rentrons dans le détail des bénéfices de cette implémentation.

1. Disponibilité en continu

Le premier avantage est évident mais crucial : la disponibilité continue. Notre assistant répond instantanément aux questions des utilisateurs, qu'il soit 2h du matin ou pendant un week-end. Cette disponibilité 24/24h et 7/7j améliore considérablement l'expérience utilisateur et influence positivement les conversions.

Cette dimension internationale est particulièrement importante pour Photobooth AI : nos utilisateurs viennent du monde entier, créant des décalages horaires qui rendaient compliqué un support traditionnel aux heures ouvrables françaises.

Cette automatisation réduit significativement la charge sur notre équipe, qui peut désormais se concentrer sur les problèmes complexes nécessitant une intervention humaine. En d'autres termes, moins de temps passé sur les questions répétitives, plus de temps pour de réels problèmes et améliorations.

2. Une expertise produit intégrée et toujours à jour

Notre assistant possède une connaissance approfondie et toujours à jour de tous les aspects de Photobooth AI : système de crédits, création d'événements, gestion des styles de génération, tarification, etc. Cette expertise garantit des réponses cohérentes et précises, basées sur notre documentation officielle.

3. Une expérience utilisateur améliorée

L'objectif pour l'expérience utilisateur est clair :

• Réponses instantanées : Plus d'attente pour obtenir des informations de base
• Navigation guidée : L'assistant dirige intelligemment les utilisateurs vers les bonnes sections de l'application
• Support multilingue : Le modèle que nous utilisons permet de répondre dans la plupart des langues utilisées par nos utilisateurs

4. Optimisation des coûts opérationnels

L'automatisation permet une réduction significative des coûts de support en traitant automatiquement les questions récurrentes. Notre équipe peut ainsi se concentrer sur sa valeur ajoutée : résoudre les problèmes complexes et améliorer le produit.

5. Collecte et traitement intelligent du feedback

L'assistant ne se contente pas de répondre aux questions. Il intègre un système intelligent de gestion du feedback qui permet, en cas de besoins spécifiques, de transmettre les demandes au support humain.

• Escalade automatique : Création automatique de tickets pour les problèmes nécessitant une intervention humaine
• Traduction automatique : Les feedbacks internationaux sont traduits en français pour notre équipe

6. Amélioration continue basée sur les données

Chaque conversation est sauvegardée et analysée, nous permettant de :

• Identifier les besoins récurrents de nos utilisateurs
• Optimiser notre produit en fonction des questions les plus fréquentes
• Améliorer continuellement les réponses de l'assistant en fonction des retours utilisateurs

Cette boucle de feedback continu nous aide à faire évoluer Photobooth AI dans la bonne direction. C'est un atout précieux pour notre roadmap produit.

Architecture technique : sous le capot

Rentrons maintenant dans les détails techniques. Notre assistant repose sur une architecture moderne utilisant les dernières innovations en IA conversationnelle :

Stack technologique

• Modèle IA : gpt-4.1-mini d'OpenAI, optimisé pour les coûts tout en maintenant une qualité élevée
• AI SDK : Vercel AI SDK pour une intégration des modèles IA et des outils
• AI Elements : pour la création de l'interface conversationnelle
• Base de données : PostgreSQL avec Prisma pour la persistance et l'analytics

Système de connaissances dynamique

L'assistant construit son contexte en temps réel en combinant :

• Un prompt système de 25 lignes spécialisé pour Photobooth AI
• Notre FAQ complète (203 lignes) mise à jour automatiquement
• Le sitemap de navigation adapté selon le statut utilisateur (connecté/anonyme)
• Un système de cache intelligent avec revalidation horaire

En conclusion

Passer de Crisp à un assistant IA personnalisé nous a permis de repenser complètement notre façon de faire du support. Plutôt que d'attendre les questions des utilisateurs, nous pouvons maintenant les anticiper et les guider plus efficacement.

Pour nous, c'est aussi d'exploiter notre expertise en agents conversationnels. Un exemple concret du potentiel d'impact positif qu'une IA bien intégrée peut avoir sur l'expérience utilisateur et les opérations d'une entreprise.

Si cette approche vous intéresse ou si vous avez des questions sur la mise en place d'un assistant IA pour votre propre produit, n'hésitez pas à nous contacter, nous serons ravis de partager notre expérience et de discuter de votre projet ! 🚀

Cependant, la diffusion progressive de ce protocole, essentielle à son adoption, s'accompagne aussi d'un certain nombre de questions et de confusions. C'est ce que nous allons tenter de clarifier dans cet article en détaillant les différents cas d'utilisation possibles et les meilleures pratiques à appliquer en fonction de vos besoins.

À quoi sert le protocole MCP ? Quels sont les cas d'utilisation possibles ? Comment utiliser ce protocole dans vos applications ? Quelles sont les limites de ce protocole ? À quels besoins répond ce protocole ?

Introduction

Force est de constater que l'utilisation des Large Language Models (LLMs) augmente de manière significative dans tous les domaines, allant de la simple utilisation par le grand public de chatbots IA comme ChatGPT (en position de quasi-monopole aujourd'hui) à l'utilisation sur-mesure dans des applications complexes, en passant par des assistants de développement comme Cursor, Zed, etc.

Mais ces outils puissants souffraient de deux problèmes majeurs:

• le manque de contexte (ex: données de la base de données, documents, etc.)
• l'impossibilité d'effectuer des actions (ex: envoyer un email, modifier un document, créer un événement, etc.)

Pour pallier au premier problème de contexte, des solutions ont été mises en place comme le Retrieval-Augmented Generation (RAG), que l'on peut voir comme une sorte de bibliothèque permettant aux LLMs d'accéder à des informations contextuelles, et le fine-tuning de modèles pour permettre aux LLMs d'être spécialisés dans un domaine précis. Ces sujets ne seront pas abordés dans cet article, mais si le fonctionnement de ces solutions vous intéresse, vous pouvez consulter Comment fonctionne un RAG ?.

Enfin, pour pallier l'impossibilité d'effectuer des actions, on a vu apparaître la notion de tools (ou outils en français).

Qu'est-ce qu'un tool ?

Un tool est une fonctionnalité qui peut être appelée par un LLM pour effectuer une tâche spécifique. Par exemple, un tool pourrait être utilisé pour envoyer un email, modifier un document, créer un événement, etc. L'appel d'un tool permet donc d'exécuter une fonction spécifique sur un serveur et de retourner un résultat qui sera soit affiché dans la conversation, soit utilisé pour donner du contexte à la requête.

1. L'utilisateur fait une demande au LLM
2. Le LLM analyse la demande et détermine s'il existe un outil qui pourrait répondre à la demande
3. Si non : Le LLM génère directement la réponse
4. Si oui : Le LLM invoque l'outil
5. Le serveur qui implémente le tool exécute l'action demandée par le tool
6. Le serveur retourne le résultat à l'utilisateur ou au LLM qui peut alors formuler une réponse complète à l'utilisateur

Où s'exécute un tool ?

Comme on peut le voir sur le schéma ci-dessus, un tool est appelé par un LLM et exécuté sur le serveur qui l'a implémenté. C'est ce serveur qui va exécuter la fonctionnalité spécifique et retourner le résultat.

C'est pour cette raison que les tools "classiques" ne peuvent pas être exécutés directement par un agent distant, par "distant" on entend un agent qui n'est pas hébergé sur le même serveur que le serveur qui implémente le tool ou dans un processus différent. Ils sont donc très utiles pour les applications qui implémentent leur propre agent IA.

Qu'est-ce que le protocole MCP ?

On l'a vu précédemment, l'infrastructure des tools est très simple, mais elle souffre du fait que leur exécution est limitée à leur propre environnement et ils ne peuvent être appelés et exécutés que dans celui-ci.

Pour pouvoir exposer des tools (entre autres) à un agent IA, on a vu apparaître le protocole Model Context Protocol (MCP). Il s'agit d'un protocole de communication qui permet de faire le pont entre des agents IA et des tools présents sur un serveur MCP.

Ce protocole repose sur deux composantes principales:

• Le serveur MCP qui implémente et expose les tools disponibles
• Le client MCP qui appelle les tools disponibles et reçoit les résultats

La communication entre ces deux entités est standardisée via un format JSON-RPC qui permet de faire transiter des ordres d'instructions (actions/procédures) entre un client et un serveur.

Le fait d'avoir deux entités distinctes nous donne la flexibilité d'utiliser le protocole MCP dans différents contextes et d'avoir nos tools accessibles depuis des environnements différents.

Les hôtes MCP

Dans la suite de cet article, nous allons parler de hôte MCP pour désigner l'entité qui implémente à la fois la communication avec un LLM et un client MCP. On pourra ainsi faire la distinction entre un hôte MCP distant et un hôte MCP local. Il est important de les différencier car ils n'auront pas les mêmes contraintes et possibilités.

Hôte MCP distant

Un hôte MCP distant ou remote est souvent un service web qui propose un chatbot IA comme ChatGPT ou Claude AI (version web). Pour savoir si un agent IA supporte le protocole MCP, il faut vérifier ses capacités dans l'interface web de l'agent IA et vérifier s'il est fait mention de Connected apps ou Connecteurs.

Hôte MCP local

Un hôte MCP local est une entité qui a pour environnement votre propre machine. Il tourne sur votre propre machine et peut donc effectuer des actions dessus. Dans cette catégorie, on peut citer les assistants de développement comme Cursor, Zed, etc., mais aussi des versions desktop d'agents conversationnels comme Claude Desktop par exemple.

Les différents types de transports

Il existe différents types de transports pour la communication entre le client et le serveur MCP:

• Stdio
• Streamable HTTP

Le choix du transport va dépendre des besoins et des contraintes de l'application.

Stdio

Le transport stdio est un transport qui utilise le standard input/output (stdin/stdout) pour la communication entre le client et le serveur. Avec ce mode de transport, tout se passe en local, c'est-à-dire que le client et le serveur sont hébergés localement et le serveur peut effectuer des actions sur la machine locale comme lire des fichiers, écrire des fichiers, etc.

Il va de pair avec un hôte MCP local. Les hôtes MCP distants n'utilisent pas ce type de transport.

Ce transport est idéal pour les assistants de développement et les applications desktop qui ont besoin d'accéder aux ressources locales de l'utilisateur.

Le serveur MCP est lancé en local en tant que sous-processus de l'hôte MCP local.

Si l'implémentation d'un serveur MCP en transport stdio vous intéresse, vous pouvez consulter Intégration d'un MCP dans une application React.

Streamable HTTP

Le transport streamable HTTP est un transport qui utilise le protocole HTTP pour la communication entre le client MCP et le serveur MCP. Il nous permet de découpler l'hôte et le serveur et de les héberger sur des serveurs différents, permettant ainsi d'utiliser des serveurs MCP avec des hôtes MCP distants et locaux.

Le serveur MCP doit être déployé sur un serveur web et accessible via une URL. L'hôte pourra ainsi appeler les tools du serveur MCP via une requête HTTP. Le transport streamable HTTP est idéal pour les hôtes MCP distants.

Dans le cadre d'un SaaS par exemple, on pourra héberger le serveur MCP sur un serveur web ou créer un endpoint /mcp dans notre API, et un utilisateur aura la possibilité d'ajouter un connecteur à son hôte MCP distant, par exemple Claude AI ou ChatGPT, pour utiliser nos tools.

Sécurité

Dans certains cas, on peut avoir besoin d'authentifier ou d'autoriser l'utilisation des outils exposés. Dans ce cas, on peut utiliser un token d'authentification ou une clé API pour sécuriser l'accès au serveur MCP. L'utilisation de ce transport nous permet donc de sécuriser l'accès aux outils exposés par le serveur MCP avec une authentification basique ou plus avancée avec OAuth 2.

Comment utiliser le protocole MCP dans vos applications ?

Tout d'abord, avant de commencer à utiliser le protocole MCP dans vos applications, il est important de comprendre comment il fonctionne et quelles sont les différentes possibilités offertes par le protocole. Ensuite, il faut définir le besoin de votre application et choisir le transport qui correspond le mieux à vos besoins.

Si votre application est un SaaS, alors vous souhaitez probablement exposer vos tools au grand public. Dans ce cas, vous aurez besoin d'utiliser le transport streamable HTTP afin de permettre aux utilisateurs de connecter leur hôte MCP distant, par exemple Claude AI ou ChatGPT, à votre serveur MCP.

Les utilisateurs d'hôtes locaux pourront aussi utiliser votre solution avec ce mode de transport.

Si votre solution est un script ou une application autonome, alors vous aurez besoin d'utiliser le transport stdio afin de permettre aux utilisateurs de connecter leur hôte MCP local à votre serveur MCP.

Si votre solution a un usage exclusivement interne, alors vous n'avez probablement pas besoin d'utiliser le protocole MCP. Exception faite si vous souhaitez utiliser des tools sur plusieurs agents IA internes. Dans ce cas, il faudra utiliser le transport stdio pour permettre aux agents IA de communiquer avec le serveur MCP (si celui-ci est sur le même serveur).

Adhésion au protocole

L'efficacité d'un MCP est directement liée à l'adhésion au protocole par les hôtes MCP distants. En effet, si un hôte MCP distant ne supporte pas le protocole MCP, alors le client MCP ne pourra pas utiliser les tools exposés par le serveur MCP. À ce jour, de plus en plus d'hôtes MCP distants supportent le protocole MCP, mais la plupart du temps l'ajout de connecteurs fait partie de fonctionnalités payantes, c'est le cas de ChatGPT et Claude AI par exemple. Ce qui freine donc la démocratisation de l'utilisation du protocole MCP par le grand public.

Registre

Il existe un registre officiel des serveurs MCP disponibles. Il est disponible sur le site de Model Context Protocol et permet de trouver les serveurs MCP disponibles et de les utiliser dans vos agents IA.

Si la mise en place de serveurs MCP par les entreprises continue de se démocratiser, il faudra s'attendre à ce que d'autres registres voient le jour pour permettre aux utilisateurs de trouver les serveurs MCP à la manière des moteurs de recherche traditionnels. Si c'est le cas, le référencement auprès de ces registres pourra devenir un enjeu majeur pour les entreprises.

Conclusion

Vous l'aurez compris, le protocole MCP est un standard qui va changer la donne dans l'écosystème IA. En permettant aux LLMs d'accéder à des données contextuelles et d'effectuer des actions concrètes, il transforme ces modèles de simples générateurs de texte en véritables assistants capables d'agir dans le monde réel.

Le choix du transport dépendra de votre contexte : stdio pour les assistants de développement et applications desktop, streamable HTTP pour les solutions SaaS et l'intégration avec des hôtes distants comme Claude AI ou ChatGPT.

Même si l'adoption par les hôtes MCP distants est encore limitée et souvent payante, la tendance est clairement à la démocratisation.

Chez Premier Octet, nous suivons de près ces évolutions. Si vous souhaitez explorer cette technologie pour vos besoins ou avez des questions sur l'implémentation, n'hésitez pas à nous contacter.

Ressources

• Model Context Protocol
• Serveurs MCP officiels
• Intégration d'un MCP dans une application React
• MCP: The Open Protocol That Turns LLM Chatbots into Intelligent Agents

Gérer une hiérarchie d’utilisateurs et de permissions dans une application peut vite devenir un casse-tête. Le plugin Organization de Better Auth propose une approche élégante et modulaire : il permet de gérer des structures multi-utilisateurs (équipes, entreprises, projets...), d’y associer des rôles et d’implémenter des permissions.

Voici la liste des points que nous allons aborder :

• la gestion du state entre client et serveur,
• la personnalisation du modèle Organization,
• la mise en place d’un système de permissions avancé,
• et enfin l’activation du mode Teams, pour les cas les plus complexes.

Séparation du state entre serveur et client

Un point de base essentiel à comprendre est que auth (serveur) et authClient (client) fonctionnent comme deux systèmes séparés, ils ne partagent pas d’état synchronisé automatiquement.

👉 En pratique :

• Les actions exécutées via auth.api ne mettent pas à jour automatiquement les hooks client (ex. useSession, useActiveOrganization).
• Il faut rafraîchir explicitement l’état client après toute action ayant un impact sur la session, l’organisation ou les rôles. Par exemple, le hook useActiveOrganization() propose un refetch() pour rafraîchir les données de l’organisation active côté client.

Ce comportement découle de la séparation entre client et serveur : Better Auth ne synchronise pas automatiquement ces deux états. Cela donne au développeur un contrôle total sur le rafraîchissement côté client. Similaire à d’autres librairies d’authentification modernes, la synchronisation automatique du state n’est généralement pas implémentée pour des raisons de performance et de sécurité.

Personnaliser le modèle Organization

Les tables nécessaires au plugin Organization sont personnalisables : il est possible de les renommer ainsi que leurs champs ou d'ajouter des champs supplémentaires. Le CLI de Better Auth se chargera ensuite de générer le schéma correspondant dans votre base de données via la commande npx @better-auth/cli generate (ici, nous utilisons Prisma avec son adapter).

Dans cet exemple, nous allons renommer Organization en Project et son champ name en title (mais dans le reste de l'article, nous continuerons à parler de organization).

plugins: [
  organization({
    schema: {
      organization: {
        modelName: 'project', // `Organization` sera renommé `Project`
        fields: {
          name: 'title', // `name` sera renommé `title`
        },
      },
      member: {
        additionalFields: {
          name: {
            // On ajoute un champ `name` à la table `Member`
            type: 'string',
            input: true,
            required: false,
          },
        },
      },
    },
  }),
]

// Voici les tables générées

model Project {
  id          String       @id
  title       String
  slug        String?
  logo        String?
  createdAt   DateTime
  metadata    String?
  members     Member[]
  invitations Invitation[]

  @@unique([slug])
  @@map("project")
}

model Member {
  id             String   @id
  organizationId String
  project        Project  @relation(fields: [organizationId], references: [id], onDelete: Cascade)
  userId         String
  user           User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  role           String
  createdAt      DateTime
  name           String?

  @@map("member")
}

model Invitation {
  id             String   @id
  organizationId String
  project        Project  @relation(fields: [organizationId], references: [id], onDelete: Cascade)
  email          String
  role           String?
  status         String
  expiresAt      DateTime
  inviterId      String
  user           User     @relation(fields: [inviterId], references: [id], onDelete: Cascade)

  @@map("invitation")
}

⚠️ Le renommage n’affecte pas les noms des méthodes SDK (authClient.organization.*, auth.api.*).

// ✅ Correct
const { data, error } = await authClient.organization.delete({
  organizationId: activeOrganization!.id,
})

// ❌ Incorrect
const { data, error } = await authClient.project.delete({
  projectId: activeProject!.id,
})

Mettre en place un système de permissions

C’est sans doute l'une des parties les plus intéressantes du plugin Organization : Better Auth fournit un système d’Access Control flexible avec son createAccessControl. Il s’appuie sur une approche déclarative de la sécurité, où chaque rôle se voit attribuer un ensemble d’actions autorisées sur des entités précises.

Résumé des termes :

• Entité → représente un objet sur lequel on agit (organization, member, invitation).
• Action → représente ce qu’on peut faire sur une entité (update, delete, etc.).
• Permission → est la combinaison entité + action (un member avec l'action create sur l'entité invitation peut créer une invitation).
• Rôle → est un ensemble de permissions accordées à un utilisateur.

Exemple de fichier de configuration :

Voici un exemple minimal pour déclarer des actions par entité et composer des rôles.

const statement = {
  organization: ['update', 'delete'],
  member: ['create', 'update', 'delete', 'update-name'],
  invitation: ['create', 'cancel'],
} as const

const ac = createAccessControl(statement)

const member = ac.newRole({
  member: ['update-name'],
})

const admin = ac.newRole({
  member: ['update', 'delete', 'update-name'],
  invitation: ['create', 'cancel'],
})

const owner = ac.newRole({
  organization: ['update', 'delete'],
  member: ['update', 'delete', 'update-name'],
  invitation: ['create', 'cancel'],
})

export { statement, ac, owner, admin, member }

Points importants

• Un utilisateur peut avoir plusieurs rôles à la fois.
• Vous pouvez définir vos propres permissions (ex. update-name).
• Si vous définissez un ac et des roles personnalisés, les permissions par défaut de Better Auth sont écrasées. Better Auth s’attend à retrouver certaines actions pour ses checks internes ; il faut donc réintroduire les actions de base si vous souhaitez utiliser les méthodes natives du plugin :
  • organization: ["update", "delete"]
  • member: ["create", "update", "delete"]
  • invitation: ["create", "cancel"]

Si une de ces actions est absente, les rôles qui ne la possèdent pas ne pourront pas exécuter les méthodes correspondantes (auth.organization.update, auth.organization.inviteMember, etc.) : elles seront considérées comme non autorisées.

Permission personnalisée

Vous vous demandez peut-être pourquoi nous avons à la fois update et update-name dans nos permissions. Intuitivement, on pourrait penser que update couvre toutes les actions de mise à jour mais dans le plugin Organization, update fait uniquement référence à la méthode updateMemberRole, c'est-à-dire au changement de rôle d'un membre.

Cela s'explique par le fait que la table Member ne contient aucun champ que l'on souhaiterait modifier par défaut autre que role. Notre permission personnalisée update-name n'aura donc de sens que si nous ajoutons un champ name à la table Member et que nous implémentons la logique métier correspondante (via nos propres routes ou actions serveur).

Vérifier les permissions côté client et côté serveur

Une bonne pratique consiste à effectuer un double check :

• Côté client → pour la logique d’interface (afficher/masquer un bouton)
• Côté serveur → pour la sécurité et la source de vérité

Côté client

authClient.organization.checkRolePermission({
  permissions: { organization: ['update'] },
  role: 'owner',
})

Cette méthode est synchrone et ne dépend pas du serveur. Elle est idéale pour ajuster l’UI selon les permissions du rôle mais ne prend pas en compte les éventuelles mises à jour récentes (changement de rôle, révocation, etc.).

Côté serveur

Le serveur reste la source de vérité.
Les rôles et permissions étant stockés en base, il faut toujours valider côté serveur :

await auth.api.hasPermission({
  headers: await headers(),
  body: {
    permissions: { organization: ['update'] },
  },
})

Voici un petit utilitaire ainsi que notre implémentation côtés client/serveur :

export type Entities = keyof typeof statement
export type PermissionFor<E extends Entities> = (typeof statement)[E][number]

// Côté Client
export const hasClientPermission = <E extends Entities, P extends PermissionFor<E>>(
  role: Role,
  entity: E,
  permission: P
) => {
  return authClient.organization.checkRolePermission({
    permissions: { [entity]: [permission] },
    role: role!,
  })
}

// Côté Serveur
'use server'






export const hasServerPermission = async <E extends Entities, P extends PermissionFor<E>>(
  entity: E,
  permission: P
) => {
  try {
    const { error, success } = await auth.api.hasPermission({
      headers: await headers(),
      body: {
        permissions: { [entity]: [permission] },
      },
    })

    if (error) {
      throw new Error(error)
    }

    if (success === false) {
      throw new Error(ERROR_MESSAGES.YOU_DONT_HAVE_PERMISSION_TO_DO_THIS_ACTION)
    }

    return success
  } catch (error) {
    if (error instanceof Error) {
      throw new Error(error.message)
    }

    console.error('[🔴 hasPermission]: ', error)
    throw new Error(ERROR_MESSAGES.AN_ERROR_OCCURRED)
  }
}

Gérer les invitations

Better Auth fournit un système intégré de gestion des invitations qui permet d’ajouter de nouveaux membres à une organisation.

Les méthodes SDK

Côté client (authClient) comme côté serveur (auth), le fonctionnement est identique :

// Côté client
// ⚠️ Pensez à rafraîchir l’état côté client si nécessaire

const { data, error } = await authClient.organization.listInvitations({
  query: {
  organizationId: "organization-id",
  },
});

// Côté serveur, la méthode équivalente à inviteMember s’appelle `createInvitation`
const { data, error } = await authClient.organization.inviteMember({
  email: "example@gmail.com",
  role: "member",
  organizationId: "org-id",
  resend: true,
  teamId: "team-id",
});

const { data, error } = await authClient.organization.acceptInvitation({
  invitationId: "invitation-id",
});

await authClient.organization.rejectInvitation({
  invitationId: "invitation-id",
});

await authClient.organization.cancelInvitation({
  invitationId: "invitation-id",
});

// Côté serveur
// ⚠️ N'oubliez pas d'inclure les headers
// Sinon la méthode renverra un statut 401 "UNAUTHORIZED"

const data = await auth.api.listInvitations({
  headers: await headers(),
  query: {
      organizationId: "organization-id",
  },
});

await auth.api.createInvitation({
  headers: await headers(),
  body: {
      email: "example@gmail.com",
      role: "member",
      organizationId: "org-id",
      resend: true,
      teamId: "team-id",
  },
});

await auth.api.acceptInvitation({
  headers: await headers(),
  body: {
  invitationId: "invitation-id",
  },
});

await auth.api.rejectInvitation({
  headers: await headers(),
  body: {
  invitationId: "invitation-id",
  },
});

await auth.api.cancelInvitation({
  headers: await headers(),
  body: {
  invitationId: "invitation-id",
  },
});

Callbacks

Après la création d'une invitation avec inviteMember (authClient) ou createInvitation (auth), Better Auth exécute automatiquement le callback sendInvitationEmail qui permet d’envoyer un e-mail personnalisé contenant l’invitationId.

Il existe également un callback onInvitationAccepted déclenché lorsque l'utilisateur accepte une invitation :

export const auth = betterAuth({
  plugins: [
    organization({
      async sendInvitationEmail(data) {
        // Gestion de votre envoi d'invitation par email
      },
      async onInvitationAccepted(data) {
        // Gestion après qu'un utilisateur accepte une invitation
      },
    }),
  ],
})

⚙️ De notre côté, dans le mail d'invitation, nous avons inclus un lien vers une page de redirection /accept-invitation/[invitationId]. Elle redirige l'utilisateur vers la page de connexion s’il n’est pas authentifié ou vers une page de gestion dédiée où il peut accepter ou refuser son invitation.

Pour aller plus loin : le mode Teams

Better Auth permet d’ajouter un niveau hiérarchique supplémentaire grâce au flag de configuration teams. Chaque organisation pourra ainsi avoir différentes équipes, chacune avec ses propres membres et rôles.

C’est particulièrement utile pour les applications complexes où :

• une entreprise regroupe plusieurs départements,
• un utilisateur a des rôles différents selon l’équipe,
• on souhaite affiner les permissions sans multiplier les organisations.

export const auth = betterAuth({
  plugins: [
    organization({
      teams: { enabled: true },
    }),
  ],
})

Better Auth gère automatiquement les relations entre organization, team et member : les utilisateurs pourront faire partie de plusieurs équipes au sein d'une même organisation. Le système d’Access Control s’applique également au niveau de l’équipe, permettant par exemple de limiter une action à un rôle dans une seule équipe.

Conclusion

Le plugin Organization de Better Auth offre une flexibilité impressionnante, il permet de construire un système d’accès robuste et lisible. Le système de permissions est entièrement extensible, vous pouvez créer vos propres entités (project, team, workspace) et définir autant de types d’actions que nécessaire pour coller à vos besoins métier !

Avec la configuration Teams, on peut modéliser des structures hiérarchiques avancées sans perdre la simplicité de son API.

Better Auth ne se limite donc pas à l’authentification, c’est un véritable socle d’autorisation moderne, extensible et agréable à utiliser.

ChatGPT ne se contente plus d'être un assistant textuel : il devient une plateforme d'applications, comparable à l'App Store pour iOS ou au Play Store pour Android.

Les Apps ChatGPT : pourquoi ?

L'Apps SDK d'OpenAI transforme ChatGPT d'un simple assistant conversationnel en une plateforme d'applications. Avec plus de 100 millions d'utilisateurs actifs hebdomadaires, ChatGPT représente désormais un canal de distribution sans précédent pour les entreprises.

Cette transformation ouvre des perspectives commerciales. Les développeurs peuvent désormais créer des applications natives qui s'intègrent parfaitement dans l'expérience utilisateur de ChatGPT, offrant un accès direct à une audience engagée.

Comme toute technologie émergente, l'Apps SDK a ses contraintes. OpenAI est très clair sur les cas d'usage à éviter :

• Des contenus longs et complexes (mieux vaut un site web classique)
• Des workflows multi-étapes complexes (ChatGPT n'est pas optimisé pour ça)
• De la publicité ou du contenu promotionnel non sollicité (ça dégrade l'expérience utilisateur)
• L'affichage d'informations sensibles directement dans la conversation

L'architecture technique : MCP au cœur

Le protocole au cœur de l'architecture : MCP

Si vous êtes développeur, voici la bonne nouvelle : l'Apps SDK ne réinvente pas la roue. Elle s'appuie sur le Model Context Protocol, un standard ouvert créé par Anthropic et adopté par OpenAI.

Qu'est-ce que cela signifie concrètement ? Que le code que vous écrivez aujourd'hui pour ChatGPT pourrait fonctionner demain avec d'autres clients MCP. C'est rare dans l'écosystème IA, et c'est une excellente nouvelle pour pérenniser vos développements.

MCP définit trois primitives essentielles :

1. List tools : votre serveur expose les outils disponibles avec leurs schémas
2. Call tools : ChatGPT invoque vos outils avec les arguments appropriés
3. Return components : chaque outil peut retourner une interface HTML à rendre

L'avantage ? Votre connecteur fonctionnera automatiquement sur ChatGPT web, mobile, et potentiellement sur tous les futurs clients compatibles MCP. Vous construisez une fois, vous déployez partout.

Choisir sa stack : TypeScript ou Python ?

Pour développer votre app, vous pouvez utiliser les SDKs MCP officiels :

TypeScript (notre préféré bien sûr ❤️) :

• @modelcontextprotocol/sdk
• Parfait si vous avez déjà une équipe Node.js/React
• S'intègre naturellement avec vos composants web existants
• Excellent outillage avec TypeScript, Zod, et l'écosystème moderne

Python :

• modelcontextprotocol/python-sdk
• Inclut FastMCP pour démarrer rapidement
• Idéal pour les équipes data science ou machine learning
• Pratique si votre backend est déjà en Python

Pour la suite de cet article, nous allons nous concentrer sur TypeScript, car c'est la stack que nous privilégions chez Premier Octet.

Implémentation technique : passons à la pratique

Construisons ensemble une app ChatGPT concrète. Nous allons créer un widget d'articles de blog Premier Octet, du serveur au composant React.

Étape 1 : Monter le serveur MCP

La première étape consiste à créer un serveur qui expose nos outils. Voici le code de démarrage :

// Initialiser le serveur MCP
const server = new McpServer({
  name: 'premier-octet-blog',
  version: '1.0.0',
})

// Charger les assets compilés du composant React
const BLOG_JS = readFileSync('web/dist/blog-widget.js', 'utf8')
const BLOG_CSS = readFileSync('web/dist/blog-widget.css', 'utf8')

// Enregistrer la ressource UI (template HTML)
server.registerResource('blog-widget', 'ui://widget/blog-articles.html', {}, async () => ({
  contents: [
    {
      uri: 'ui://widget/blog-articles.html',
      mimeType: 'text/html+skybridge',
      text: `
        <div id="blog-root"></div>
        ${BLOG_CSS ? `<style>${BLOG_CSS}</style>` : ''}
        <script type="module">${BLOG_JS}</script>
      `.trim(),
    },
  ],
}))

Rien de compliqué ici : on initialise le serveur, on charge notre bundle React compilé, et on l'enregistre comme ressource. Le mimeType: 'text/html+skybridge' est crucial : c'est le signal qui dit à ChatGPT "voici une interface à afficher". Skybridge est le runtime sandboxé de ChatGPT.

Étape 2 : Définir un outil

Maintenant, créons un outil que ChatGPT pourra invoquer. Vous définissez ce que votre app peut faire, et ChatGPT décide quand l'utiliser en fonction du contexte de la conversation.

server.registerTool(
  'show_blog_articles',
  {
    title: 'Afficher les articles du blog Premier Octet',
    description:
      "Utilisez cet outil quand l'utilisateur veut découvrir les derniers articles du blog Premier Octet ou rechercher des articles par thème",
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: "Catégorie d'articles (ex: react, typescript, openai)",
        },
        limit: { type: 'number', description: "Nombre d'articles à afficher (défaut: 6)" },
      },
      required: [],
    },
    _meta: {
      'openai/outputTemplate': 'ui://widget/blog-articles.html',
      'openai/widgetAccessible': true, // Permet les appels depuis le composant
      'openai/toolInvocation/invoking': 'Chargement des articles...',
      'openai/toolInvocation/invoked': 'Articles affichés',
    },
  },
  async ({ category, limit = 6 }, context) => {
    // Récupérer les articles depuis votre API
    const articles = await fetchBlogArticles({ category, limit })

    return {
      // Données structurées pour le modèle ET le composant
      structuredContent: {
        articles: articles.map((article) => ({
          id: article.id,
          title: article.title,
          excerpt: article.excerpt,
          date: article.date,
          author: article.author,
          tags: article.tags,
          slug: article.slug,
        })),
        total: articles.length,
        category: category || 'tous',
      },
      // Texte pour le transcript de conversation
      content: [
        {
          type: 'text',
          text: `Voici ${articles.length} articles du blog Premier Octet${
            category ? ` sur le thème "${category}"` : ''
          }.`,
        },
      ],
      // Métadonnées privées (invisibles au modèle)
      _meta: {
        fullArticles: articles, // Données complètes pour le UI
        searchQuery: category,
      },
    }
  }
)

Remarquez comment nous séparons clairement les données :

• structuredContent : ce que le modèle ET le composant voient (gardez ça concis !)
• content : le texte qui apparaîtra dans la conversation
• _meta : les données privées, invisibles au modèle mais disponibles pour votre UI

Étape 3 : Construire le composant React

Vous développez déjà des composants React ? Bonne nouvelle : vous pouvez les utiliser ! La seule différence, c'est qu'ils tournent dans une iframe sandboxée et communiquent avec ChatGPT via l'API window.openai.

interface BlogData {
  articles: Array<{
    id: string
    title: string
    excerpt: string
    date: string
    author: string
    tags: string[]
    slug: string
  }>
  total: number
  category: string
}

function BlogWidget() {
  // Récupérer les données initiales du tool
  const initialData = window.openai?.toolOutput as BlogData
  const [articles, setArticles] = useState(initialData)

  // Persister l'état local dans ChatGPT
  const saveState = async (newArticles: BlogData) => {
    setArticles(newArticles)
    await window.openai?.setWidgetState?.({
      version: 1,
      articles: newArticles,
      lastModified: Date.now(),
    })
  }

  // Appeler un outil depuis le composant
  const searchArticles = async (category: string) => {
    await window.openai?.callTool('show_blog_articles', {
      category,
      limit: 6,
    })
  }

  // Gérer les changements de layout
  const displayMode = window.openai?.displayMode || 'inline'
  const maxHeight = window.openai?.maxHeight

  return (
    <div
      style={{ maxHeight }}
      className={displayMode === 'fullscreen' ? 'fullscreen-layout' : 'inline-layout'}
    >
      <div className="blog-header">
        <h2>Articles Premier Octet</h2>
        <div className="category-filters">
          <button onClick={() => searchArticles('')}>Tous</button>
          <button onClick={() => searchArticles('react')}>React</button>
          <button onClick={() => searchArticles('typescript')}>TypeScript</button>
          <button onClick={() => searchArticles('openai')}>OpenAI</button>
        </div>
      </div>

      <div className="articles-grid">
        {articles.articles.map((article) => (
          <article key={article.id} className="article-card">
            <h3>{article.title}</h3>
            <p className="article-excerpt">{article.excerpt}</p>
            <div className="article-meta">
              <span className="author">{article.author}</span>
              <span className="date">{new Date(article.date).toLocaleDateString('fr-FR')}</span>
            </div>
            <div className="article-tags">
              {article.tags.map((tag) => (
                <span key={tag} className="tag">
                  {tag}
                </span>
              ))}
            </div>
          </article>
        ))}
      </div>
    </div>
  )
}

// Monter le composant
createRoot(document.getElementById('blog-root')!).render(<BlogWidget />)

Ce composant illustre les concepts clés :

• Lecture des données initiales depuis toolOutput
• Persistance de l'état avec setWidgetState (pour que l'état survive aux re-rendus)
• Appels d'outils depuis le composant avec callTool pour filtrer par catégorie
• Adaptation au layout (inline vs fullscreen)
• Interface utilisateur avec filtres et grille d'articles

Étape 4 : l'API window.openai

L'API window.openai est votre pont entre le composant et ChatGPT :

// Données
window.openai.toolInput // Arguments passés à l'outil
window.openai.toolOutput // Réponse de l'outil (structuredContent)
window.openai.widgetState // État persisté entre les rendus

// Actions
await window.openai.setWidgetState({
  /* state */
})
await window.openai.callTool('tool_name', {
  /* args */
})
await window.openai.sendFollowupTurn({ prompt: '...' })
await window.openai.requestDisplayMode({ mode: 'fullscreen' })

// Layout & contexte
window.openai.displayMode // "inline" | "pip" | "fullscreen"
window.openai.maxHeight // Hauteur max disponible
window.openai.locale // "fr-FR", "en-US"...
window.openai.theme // "light" | "dark"

Ces méthodes couvrent 90% de vos besoins. Le reste de la documentation officielle complètera pour les cas avancés.

Étape 5 : sécuriser avec OAuth 2.1

Si votre app accède à des données utilisateur (ce qui sera souvent le cas), vous devez implémenter l'authentification. Bonne nouvelle : l'Apps SDK supporte OAuth 2.1 de bout en bout, avec vérification automatique des tokens.

// Configurer l'authentification
const mcp = new FastMCP({
  name: 'secure-blog',
  auth: {
    issuerUrl: 'https://your-tenant.auth0.com',
    resourceServerUrl: 'https://api.example.com/mcp',
    requiredScopes: ['blog:read', 'blog:write'],
  },
})

// Vérifier les tokens sur chaque appel
mcp.registerTool(
  'show_blog_articles',
  {
    /* ... */
  },
  async ({ projectId }, { token }) => {
    // Le token est automatiquement vérifié
    const userId = token.subject
    const hasAccess = token.scopes.includes('blog:read')

    if (!hasAccess) {
      throw new Error('Insufficient permissions')
    }

    // Charger les données de l'utilisateur
    return await loadUserBoard(userId, projectId)
  }
)

Pour accélérer l'implémentation, utilisez Better Auth. Il supporte OAuth 2.1, l'enregistrement dynamique des clients, et la gestion des scopes nativement.

Rendre votre app découvrable

La découverte de votre app par les utilisateurs est un enjeu crucial.

Les différents chemins vers votre app

ChatGPT offre plusieurs façons aux utilisateurs de découvrir et d'utiliser votre app :

1. Mention explicite : "Montre-moi les articles du blog de Premier Octet"
2. Découverte conversationnelle : le modèle choisit votre app selon le contexte
3. Directory : répertoire des apps avec métadonnées et captures d'écran
4. Launcher : bouton + dans le composer

La qualité de vos métadonnées fait toute la différence. ChatGPT décide d'appeler votre outil en analysant sa description. Comparez :

// ✅ Bon : description action-oriented et contextuelle
description: "Utilisez cet outil quand l'utilisateur veut visualiser les articles du blog de Premier Octet"

// ❌ Mauvais : trop vague, le modèle ne saura pas quand l'utiliser
description: 'Un outil pour afficher des articles'

Sécurité et vie privée

Une app ChatGPT a accès à des données utilisateur sensibles. OpenAI impose des standards stricts de sécurité, et vous devriez en faire autant.

Les principes de base

OpenAI impose des standards stricts :

1. Principe du moindre privilège : ne demandez que les scopes nécessaires
2. Consentement explicite : les utilisateurs doivent comprendre ce qu'ils autorisent
3. Défense en profondeur : validez tout côté serveur, même si le modèle l'a fourni
4. Minimisation des données : ne collectez que ce qui est strictement nécessaire

Sandboxing des composants

Les composants s'exécutent dans une iframe avec CSP stricte :

// Définir votre CSP
server.registerResource('blog-widget', 'ui://widget/blog-articles.html', {}, async () => ({
  contents: [
    {
      uri: 'ui://widget/blog-articles.html',
      mimeType: 'text/html',
      text: componentHtml,
      _meta: {
        'openai/widgetCSP': {
          connect_domains: ['https://api.example.com'],
          resource_domains: ['https://cdn.example.com'],
        },
      },
    },
  ],
}))

Pourquoi TypeScript est votre meilleur allié

On en a parlé au début, mais revenons-y : TypeScript est vraiment le choix optimal pour l'Apps SDK. Voici pourquoi :

Les avantages concrets

1. Type safety : Zod + TypeScript vous évitent les bugs. Vos schémas serveur et client sont toujours cohérents.
2. Réutilisabilité : vos composants React existants fonctionnent directement.
3. Tooling performant : esbuild compile en millisecondes, TypeScript détecte les erreurs avant l'exécution
4. Isomorphisme : un seul langage, des types partagés serveur/client, zéro friction

Exemple : types partagés

// shared/types.ts


export const ArticleSchema = z.object({
  id: z.string(),
  title: z.string(),
  excerpt: z.string(),
  date: z.string(),
  author: z.string(),
  tags: z.array(z.string()),
  slug: z.string(),
})

export const BlogDataSchema = z.object({
  articles: z.array(ArticleSchema),
  total: z.number(),
  category: z.string(),
})

export type Article = z.infer<typeof ArticleSchema>
export type BlogData = z.infer<typeof BlogDataSchema>

// Serveur
server.registerTool(
  'show_blog_articles',
  {
    inputSchema: z.object({
      category: z.string().optional(),
      limit: z.number().optional(),
    }),
  },
  async ({ category, limit = 6 }) => {
    const blogData: BlogData = await fetchBlogArticles({ category, limit })
    return { structuredContent: blogData }
  }
)

// Client React
function BlogWidget() {
  const blogData = window.openai?.toolOutput as BlogData
  // TypeScript sait que blogData.articles existe !
}

Vous voyez l'idée : un type défini une fois, utilisé partout. Zéro duplication, zéro désynchronisation.

L'UX comme critère de succès

Une excellente tech ne suffit pas si l'expérience utilisateur est mauvaise. OpenAI a publié des design guidelines très complètes. Voici ce qu'il faut retenir.

Les trois modes d'affichage

L'Apps SDK vous permet de choisir comment votre app s'affiche. Chaque mode a son usage :

1. Inline : une carte légère dans la conversation — parfait pour une action simple (confirmer une réservation)
2. Picture-in-Picture : une fenêtre flottante qui reste visible — idéal pour du contenu continu (vidéo, jeu)
3. Fullscreen : une vue immersive avec le composer ChatGPT intégré — pour de l'édition complexe ou de l'exploration

function BlogWidget() {
  const displayMode = window.openai?.displayMode

  if (displayMode === 'fullscreen') {
    return <FullscreenBlogView />
  }

  return (
    <InlineCard>
      <button
        onClick={() => {
          window.openai?.requestDisplayMode({ mode: 'fullscreen' })
        }}
      >
        Ouvrir en plein écran
      </button>
    </InlineCard>
  )
}

Le passage d'un mode à l'autre doit être fluide. Testez bien les trois cas.

Les principes de design à respecter

OpenAI insiste sur 5 principes fondamentaux. Ils peuvent sembler évidents, mais en pratique, beaucoup d'apps les ignorent :

• Conversationnel : votre app doit prolonger ChatGPT, pas créer une rupture
• Intelligent : utilisez le contexte de la conversation pour adapter l'interface
• Simple : une action claire par interaction — ne surchargez pas
• Responsive : ça doit être rapide. Si votre tool met 3 secondes à répondre, c'est trop
• Accessible : dark mode, tailles de texte, lecteurs d'écran — faites les choses bien

Gardez ces 5 principes constamment à l'esprit lors du développement.

Tester et débugger efficacement

MCP Inspector : votre meilleur ami

Avant même de toucher à ChatGPT, vous devez tester localement. Le MCP Inspector est l'outil indispensable :

npx @modelcontextprotocol/inspector@latest
# Pointer vers http://localhost:3000/mcp

L'inspector permet de :

• Lister tous les outils exposés
• Appeler les outils avec des paramètres
• Visualiser les réponses JSON
• Tester le rendu des composants

Tests automatisés

describe('Blog Articles Tool', () => {
  it('should return articles data', async () => {
    const result = await server.callTool('show_blog_articles', {
      category: 'react',
      limit: 3,
    })

    expect(result.structuredContent).toHaveProperty('articles')
    expect(result.structuredContent.articles).toBeInstanceOf(Array)
    expect(result.structuredContent.total).toBeGreaterThan(0)
  })

  it('should filter by category', async () => {
    const result = await server.callTool('show_blog_articles', {
      category: 'typescript',
    })

    expect(result.structuredContent.category).toBe('typescript')
  })
})

Debug dans ChatGPT

En mode développeur :

1. Ouvrir les DevTools du navigateur
2. Les composants s'affichent dans une iframe
3. Les erreurs apparaissent dans la console
4. Utiliser console.log dans vos composants

Cas d'usage réels : inspiration

OpenAI fournit l'app de démonstration Pizzaz avec plusieurs exemples :

• Pizzaz List : liste classée de restaurants
• Pizzaz Map : carte interactive Mapbox
• Pizzaz Carousel : galerie horizontale
• Pizzaz Video : lecteur vidéo avec timeline
• Pizzaz Album : vue détaillée d'un lieu

Code source disponible

Pour conclure

L'Apps SDK transforme ChatGPT : d'un chatbot à une plateforme d'applications conversationnelles.

Techniquement, c'est bien pensé. L'architecture MCP, le support TypeScript, et l'intégration React rendent le développement accessible à toute équipe web moderne. Les guidelines strictes, bien que contraignantes, garantissent une expérience utilisateur cohérente.

Si vous envisagez de construire une app ChatGPT, ou simplement d'explorer le sujet, parlons-en ensemble.

👉 Ressources utiles :

• Documentation officielle Apps SDK
• Model Context Protocol
• Exemples GitHub
• TypeScript SDK

👋

Très récemment, un tournant important a eu lieu : Auth.js rejoint Better Auth.

Better Auth devient donc le successeur officiel d'Auth.js et nous propose une vision plus large ainsi qu'une approche plus moderne de l’authentification.

Dans cet article, nous partageons notre retour d’expérience : installation, migration depuis Supabase et découverte des plugins.

Sessions : une évolution d’approche

Historiquement, Auth.js proposait deux stratégies :

1. des sessions stateless avec un token JWT qui ne nécessitent pas de base de données. Une stratégie légère et pratique, mais si les données de la session évoluent (rôles, permissions…), il faut mettre en place des mécanismes supplémentaires pour invalider les tokens devenus obsolètes. Cette stratégie est celle appliquée par défaut.
2. des sessions stateful stockées en base de données via un adapter (Prisma, Mongo…) et vérifiées à chaque requête. Elles permettent de garder les permissions constamment à jour, d’invalider immédiatement une session (ex. logout forcé) et de gérer facilement plusieurs appareils. En contrepartie, cette stratégie nécessite plus de ressources, puisqu’elle implique des appels serveur plus fréquents.

Better Auth, lui, a fait le choix d’un modèle basé avant tout sur des sessions stateful. Il propose toutefois un plugin Bearer Token Authentication qui permet de mettre en place des sessions stateless.

Installation et gestion de la base de données

Là où Auth.js reposait sur des schémas à intégrer manuellement, Better Auth fournit un CLI qui génère directement les tables nécessaires. Résultat : une installation rapide, standardisée et avec moins de risques d’erreurs.

En pratique, voici la mise en place avec Prisma après avoir installé la librairie :

npx @better-auth/cli generate
npx prisma migrate dev

const prisma = new PrismaClient();

export const auth = betterAuth({
  secret: process.env.BETTER_AUTH_SECRET,
  database: prismaAdapter(prisma, {
    provider: "postgresql",
  }),
});

const authClient = createAuthClient();

export const {
  useSession,
  getSession,
  signIn,
  signOut,
  changeEmail,
  changePassword,
  updateUser,
} = authClient;

export const { GET, POST } = toNextJsHandler(auth.handler);

Et voilà. ✨ Inscription, connexion, gestion des sessions, modification d’email, réinitialisation de mot de passe, tout est fonctionnel et accessible depuis l'API via les appels auth.api pour le côté serveur et authClient pour le côté client.

Better Auth ne fournit pas d'UI prête à l'emploi mais après une configuration rapide, ses méthodes permettent une intégration sans prise de tête, que ce soit pour la connexion par credentials ou via des providers sociaux comme Google, Apple, GitHub, etc.

Migration depuis Supabase

Nous avons également testé la migration depuis Supabase sur l'une de nos applications. Encore une fois, le processus est très simple :

1. Récupérer l’URL de la base de données sur Supabase.
2. Générer les tables Better Auth avec le CLI.
3. Lancer le script officiel pour convertir les utilisateurs.

⚠️ Limite actuelle : Supabase utilise bcrypt pour le hachage des mots de passe tandis que Better Auth repose sur scrypt. Les utilisateurs devront donc réinitialiser leur mot de passe après migration. En production, une communication claire (mailing, bannière, etc.) est indispensable.

Plugins : aller plus loin

Tandis qu'Auth.js se concentrait sur les providers (Google, GitHub, Credentials, etc.), Better Auth propose en plus des plugins qui adressent des besoins métiers concrets : organisations, rôles avancés, 2FA, magic links.

Exemple : Organization est un plugin qui facilite la gestion d’équipes ou de structures dans une application. Il génère automatiquement les tables nécessaires et expose des méthodes prêtes à l’emploi pour :

• créer une organisation,
• inviter des membres,
• attribuer et modifier des rôles,
• gérer les droits d’accès associés.

En pratique, cela permet de mettre en place un système complet de gestion multi-utilisateurs sans avoir à réécrire nous-mêmes toute la logique métier.

export const auth = betterAuth({
    plugins: [organization()]
})

export const authClient = createAuthClient({
    plugins: [organizationClient()]
})

En quelques lignes seulement, les plugins ouvrent la porte à des fonctionnalités avancées : 2FA pour renforcer la sécurité, magic links pour simplifier la connexion, des outils de gestion administrateur (dont la très utile impersonification), et bien plus encore !

Conclusion

Tout au long de cet article, le mot simple est revenu plus d’une fois et ce n’est pas un hasard. Better Auth a été conçu avec la Developper Experience en tête et cela se ressent dès la première installation : tout est fluide et agréable à utiliser.

Au-delà de cette facilité d’usage, Better Auth est désormais le successeur officiel d’Auth.js. C’est un outil solide qui combine sécurité, extensibilité et rapidité de mise en place.

Chez Premier Octet, Better Auth est désormais notre solution de référence pour gérer l’authentification dans les projets clients. Sa simplicité d’intégration et sa flexibilité en font un choix naturel pour nos développements.

👉 Si vous utilisez déjà Auth.js, Better Auth vaut clairement la migration.

Concrètement, un utilisateur peut demander un produit dans ChatGPT, voir une fiche détaillée et finaliser son achat via un bouton “Acheter”. Côté marchand, cela implique de mettre en place trois briques techniques :

• un flux produit (Product Feed) pour rendre le catalogue accessible,
• une API Checkout pour gérer les sessions et les commandes,
• un mécanisme de paiement délégué qui s’appuie notamment sur Stripe.

L’accès est pour l’instant limité aux États-Unis et nécessite une validation d’OpenAI, mais l’annonce donne une idée claire de la direction que prend l’e-commerce conversationnel.

Dans cet article, nous expliquons en détail comment fonctionne le protocole, ses trois piliers techniques, et proposons une roadmap de préparation pour anticiper une intégration future.

Qu’est-ce que l’Agentic Commerce Protocol ?

L’ACP est une spécification ouverte qui définit comment un système tiers (ici ChatGPT) peut afficher un catalogue produit, initier un checkout et déléguer le paiement à un PSP (Payment Service Provider) comme Stripe.

👉 L’objectif : permettre à vos clients de passer de la recherche au paiement en un seul flux conversationnel.

Comment fonctionne l’e-commerce conversationnel dans ChatGPT ?

Prenons l'exemple d'un utilisateur qui demanderait : "Trouve-moi des chaussures de running à moins de 100 €".

ChatGPT peut alors :

1. Afficher les produits de votre catalogue (via le Product Feed)
2. Proposer un bouton “Acheter”
3. Déclencher un checkout complet directement dans la conversation

Trois flux de données orchestrent ce parcours :

• Product Feed : ChatGPT indexe vos produits pour les rendre découvrables
• API Checkout : vous gérez les sessions panier et la finalisation des commandes
• Paiement délégué : vos PSP gèrent la transaction en toute sécurité

Pilier 1 : Le Product Feed 📦

Premier élément à mettre en place : le Product Feed. Avant que ChatGPT puisse recommander vos produits, il faut lui fournir un catalogue structuré et à jour. Sans ça, même si votre API Checkout est parfaite, vos produits resteront invisibles.

Le format

Vous avez le choix : TSV, CSV, XML ou JSON. Prenez celui qui s'intègre le mieux à votre système existant. Nous recommandons JSON pour sa flexibilité et sa lisibilité, mais CSV fera très bien l'affaire si c'est ce que votre système génère naturellement.

Le feed est poussé vers un endpoint OpenAI qui vous sera fourni lors de votre onboarding. Pas de pull côté OpenAI, c'est vous qui envoyez les mises à jour.

Les champs

La structure est assez classique. Voici un exemple de produit que OpenAI attend :

[
  {
    "id": "SKU12345",
    "title": "Chaussures de running Nike Air Zoom Pegasus",
    "description": "Chaussures légères avec amorti réactif...",
    "link": "https://yourshop.com/products/SKU12345",
    "price": "89.99 EUR",
    "currency": "eur",
    "availability": "in_stock",
    "image_link": "https://yourshop.com/images/SKU12345.jpg",
    "brand": "Nike",
    "condition": "new",
    "weight": "280 g",
    "enable_search": true,
    "enable_checkout": true
  }
]

Les deux derniers flags (enable_search et enable_checkout) sont spécifiques à OpenAI et vous donnent un contrôle granulaire : un produit peut être découvrable dans la recherche sans être achetable directement.

Vous pouvez retrouver la liste complète des champs dans la documentation d'OpenAI.

Gérer les variantes

Point important si vous vendez des produits déclinables : les variantes. Si vous vendez une chaussure en plusieurs tailles et couleurs, utilisez item_group_id pour regrouper les variantes. Concrètement, ça ressemble à ça :

[
  {
    "id": "SKU12345-42-BLUE",
    "item_group_id": "SKU12345",
    "title": "Nike Air Zoom Pegasus - Bleu",
    "color": "Bleu",
    "size": "42"
    // ...
  },
  {
    "id": "SKU12345-43-BLUE",
    "item_group_id": "SKU12345",
    "title": "Nike Air Zoom Pegasus - Bleu",
    "color": "Bleu",
    "size": "43"
    // ...
  }
]

ChatGPT saura alors proposer les différentes options au moment de l'achat.

Pilier 2 : L'API Checkout 🛍️

Une fois vos produits indexés dans ChatGPT, il faut gérer la partie achat. C'est le cœur du système, et c'est là que vous allez passer le plus de temps de développement.

Vous devez exposer 5 endpoints que ChatGPT va appeler pour gérer le cycle de vie d'un achat. L'idée est simple : ChatGPT orchestre, mais c'est vous qui calculez tout (prix, taxes, shipping) et qui décidez in fine d'accepter ou non la commande.

1. Créer une session

POST /checkout_sessions

C'est le point d'entrée. Quand l'utilisateur clique sur "Acheter" dans ChatGPT, cet endpoint est appelé avec les items que l'utilisateur veut acheter et éventuellement son adresse de livraison :

Requête :

{
  "items": [{ "id": "SKU12345-42-BLUE", "quantity": 1 }],
  "fulfillment_address": {
    "name": "Bptiste Adrien",
    "line_one": "18 avenue Parementier",
    "city": "Paris",
    "postal_code": "75018",
    "country": "FR"
  }
}

2. Mettre à jour la session

POST /checkout_sessions/{checkout_session_id}

L'utilisateur change d'avis sur son mode de livraison ou modifie son adresse ? Pas de problème. ChatGPT appelle cet endpoint avec les nouvelles données, vous recalculez taxes et frais de port, et vous retournez le même format de réponse que lors de la création.

C'est important que ce endpoint soit rapide, car l'utilisateur peut le déclencher plusieurs fois en ajustant ses choix.

3. Finaliser l'achat

POST /checkout_sessions/{checkout_session_id}/complete

C'est le moment critique : l'utilisateur a validé son paiement.

Requête :

{
  "buyer": {
    "first_name": "Baptiste",
    "last_name": "Adrien",
    "email": "hello@premieroctet.com"
  },
  "payment_data": {
    "token": "spt_1234567890",
    "provider": "stripe",
    "billing_address": {
      /* ... */
    }
  }
}

À ce moment, vous :

1. Chargez le moyen de paiement via votre PSP (Stripe, etc.)
2. Créez la commande dans votre système
3. Retournez l'ID de commande et un lien de suivi

Réponse :

{
  "id": "checkout_session_abc123",
  "status": "completed",
  "order": {
    "id": "order_789",
    "permalink_url": "https://yourshop.com/orders/order_789"
  }
  // ... reste de l'état du checkout
}

Le permalink_url est crucial : c'est là que l'utilisateur pourra suivre sa commande.

4 & 5. Récupérer et annuler

GET /checkout_sessions/{checkout_session_id}
POST /checkout_sessions/{checkout_session_id}/cancel

Ces deux derniers endpoints sont plus simples. Le GET permet à ChatGPT de vérifier l'état actuel d'une session (utile en cas de reconnexion ou de perte de contexte). Le POST cancel permet à l'utilisateur d'annuler explicitement une session en cours.

Dans les deux cas, retournez l'état complet de la session avec le bon statut.

Les webhooks

L'API Checkout n'est pas unidirectionnelle. Vous devez aussi envoyer des webhooks vers OpenAI pour notifier des changements d'état de la commande. C'est comme ça que ChatGPT saura que la commande est confirmée, expédiée, livrée, ou annulée.

{
  "type": "order_updated",
  "data": {
    "type": "order",
    "checkout_session_id": "checkout_session_abc123",
    "permalink_url": "https://yourshop.com/orders/order_789",
    "status": "shipped",
    "refunds": []
  }
}

Pilier 3 : Le paiement 💳

Dernier pilier, et non des moindres : le paiement. C'est là que beaucoup se posent des questions légitimes sur la sécurité et la conformité PCI. OpenAI ne touche jamais directement à l'argent. Le protocole définit simplement comment transmettre de manière sécurisée les informations de paiement entre l'utilisateur, ChatGPT, et votre système. Vous restez en contrôle, et vous utilisez votre PSP habituel.

Option 1 : Vous utilisez déjà Stripe

C'est l'option la plus simple. Stripe a développé un mode "agentic payments" qui s'active en une ligne de code :

stripe.agentic_payments.enable()

Stripe gère alors la création et la transmission du token de paiement. Côté checkout, vous recevez un payment_data.token classique que vous chargez comme d'habitude.

Option 2 : Vous utilisez un autre PSP

Pas de Stripe dans votre stack ? Pas de panique, vous avez deux solutions.

A. Via Stripe Shared Payment Token API

Même si vous ne processez pas les paiements avec Stripe, vous pouvez utiliser leur API uniquement pour recevoir le token sécurisé. C'est une couche intermédiaire qui ne change rien à votre PSP principal (Adyen, Braintree, etc.). Vous recevez un token via Stripe, puis vous chargez le paiement avec votre PSP habituel.

B. Implémentation directe (PSP ou PCI DSS Level 1 uniquement)

Si vous êtes un PSP ou un merchant PCI DSS Level 1 avec votre propre vault, vous pouvez implémenter directement l'endpoint du protocole. Attention, cette option implique de manipuler directement les données de carte. Ne vous lancez là-dedans que si vous avez déjà l'infrastructure et la conformité PCI en place.

Quelques points d'attention

Avant de vous lancer, voici quelques limitations (à date) à garder en tête :

• Géographie : USA uniquement pour l'instant
• Approbation : pas d'accès automatique, il faut postuler
• Single-item : pas de panier multi-produits (pour le moment)
• Pas de promo codes complexes : gardez la logique simple au début

Le mot de la fin

Voilà, vous avez maintenant une vision complète de ce qu'implique l'implémentation de l'Agentic Commerce Protocol.

Pour les développeurs, c'est une intégration REST classique. Rien de sorcier si vous avez déjà un système de checkout robuste. L'effort principal sera d'adapter votre logique métier (pricing, taxes, shipping) pour qu'elle soit exposable via une API.

Pour les business, c'est un nouveau canal à tester. 700 millions d'utilisateurs de ChatGPT représentent une audience considérable. Même si l'accès est limité pour le moment, préparer votre infrastructure maintenant vous donnera un avantage quand les vannes s'ouvriront.

Chez Premier Octet, nous suivons de près cette évolution et commençons à accompagner nos premiers clients sur le sujet. Si vous envisagez d'implémenter l'Agentic Commerce Protocol et avez besoin d'accompagnement technique, n'hésitez pas à nous contacter. On serait ravis d'échanger sur votre projet !

Ressources utiles :

• Documentation officielle OpenAI
• Documentation de l'Agentic Commerce Protocol
• Documentation du Stripe

👋

Installation

Créons un simple projet React avec Vite :

bun create vite@latest

Nous devrons modifier le package.json afin de faire pointer les versions de React et React DOM vers la version canary.

Cas d'utilisation

Nous allons réaliser un cas d'utilisation qui peut s'avérer fréquent : la gestion d'un formulaire en plusieurs étapes.

Utilisation basique

Actuellement, l'utilisation la plus classique serait la suivante :

function App() {
  const [step, setStep] = useState(1);

return (

<div
  style={{
    margin: '1rem',
    display: 'flex',
    alignItems: 'center',
    flex: 1,
    flexDirection: 'column',
    gap: '1rem',
  }}
>
  <div style={{ display: 'flex', gap: '1rem' }}>
    <button type="button" onClick={() => setStep(1)}>
      Step 1
    </button>
    <button type="button" onClick={() => setStep(2)}>
      Step 2
    </button>
  </div>
  {step === 1 && <Step1 />}
  {step === 2 && <Step2 />}
</div>
); }

const Step1 = () => {
  const [name, setName] = useState("");

  return (
    <input
      value={name}
      onChange={(e) => setName(e.target.value)}
      name="name"
      placeholder="Name"
    />
  );
};

const Step2 = () => {
  const [address, setAddress] = useState("");

return (

<input
  value={address}
  onChange={(e) => setAddress(e.target.value)}
  name="address"
  placeholder="Address"
/>
); };

En l'état, ce bout de code est fonctionnel mais présente un inconvénient en terme d'UX : lorsque l'on remplit un champ puis que l'on change d'étape, l'état de ce champ est perdu. C'est logique : notre composant a été démonté. Pour palier à ça, on pourrait tout à fait modifier le code afin de cacher le composant, de sorte qu'il soit toujours présent dans l'arbre React.

function App() {
  const [step, setStep] = useState(1);

  return (
    <div
      style={{
        margin: "1rem",
        display: "flex",
        alignItems: "center",
        flex: 1,
        flexDirection: "column",
        gap: "1rem",
      }}
    >
      <div style={{ display: "flex", gap: "1rem" }}>
        <button type="button" onClick={() => setStep(1)}>
          Step 1
        </button>
        <button type="button" onClick={() => setStep(2)}>
          Step 2
        </button>
      </div>
      <div style={step === 2 ? { display: "none" } : {}}>
        <Step1 />
      </div>
      <div style={step === 1 ? { display: "none" } : {}}>
        <Step2 />
      </div>
    </div>
  );
}

C'est fonctionnel mais pas idéal, imaginons que nos composants doivent gérer des événements, ou du contenu interactif comme une vidéo, nous devrions quand même passer une prop afin de gérer leur activation / désactivation. De même, la présence d'un effect (useEffect ou useLayoutEffect) devrait avoir son déclenchement réglé selon cette prop. Bien que cela soit possible, cela rajouterait de la complexité à notre composant.

Le composant Activity à la rescousse

C'est dans ce cadre qu'intervient le composant Activity. Son rôle est simple : cacher le noeud du DOM avec un display: none, conserver l'état du noeud React, et n'exécuter les effects uniquement quand notre composant est visible. En quelque sorte, c'est comme si notre composant était partiellement monté et démonté.

function App() {
  const [step, setStep] = useState(1);

  return (
    <div
      style={{
        margin: "1rem",
        display: "flex",
        alignItems: "center",
        flex: 1,
        flexDirection: "column",
        gap: "1rem",
      }}
    >
      <div style={{ display: "flex", gap: "1rem" }}>
        <button type="button" onClick={() => setStep(1)}>
          Step 1
        </button>
        <button type="button" onClick={() => setStep(2)}>
          Step 2
        </button>
      </div>
      <Activity mode={step === 1 ? "visible" : "hidden"}>
        <Step1 />
      </Activity>
      <Activity mode={step === 2 ? "visible" : "hidden"}>
        <Step2 />
      </Activity>
    </div>
  );
}

La saisie de texte est maintenant conservée entre chaque changement d'étape. En inspectant le DOM, on peut voir qu'un style display: none est appliqué à notre input caché.

Pour aller plus loin, on peut observer le comportement des effects, à l'aide de simples console.log.

const Step2 = () => {
  const [address, setAddress] = useState("");

  useEffect(() => {
    console.log("Step2 mounted");

    return () => {
      console.log("Step2 unmounted");
    };
  }, []);

  useLayoutEffect(() => {
    console.log("Step2 layout mounted");

    return () => {
      console.log("Step2 layout unmounted");
    };
  }, []);

  return (
    <input
      value={address}
      onChange={(e) => setAddress(e.target.value)}
      name="address"
      placeholder="Address"
    />
  );
};

En rafraichissant la page, on peut voir qu'aucun des logs ne s'affiche. Pourtant, notre input est bien dans le DOM. En cliquant sur notre étape 2, nos effects sont bien déclenchés, et les fonctions de cleanup sont exécutées si l'on revient à l'étape 1.

Pré-rendu et données distantes

Afin de récupérer des données distantes, un cas d'utilisation courant serait d'effectuer une requête dans un useEffect. Or on a vu précédemment que les effects ne sont pas exécutés dans le cadre de l'utilisation d'Activity. Pour palier à cela, nous allons utiliser le hook use.

const fetchAddress = new Promise<string>((resolve) => {
  resolve("Some street name");
});

const Step2 = () => {
  const addressData = use(fetchAddress);
  const [address, setAddress] = useState(addressData);

  return (
    <input
      value={address}
      onChange={(e) => setAddress(e.target.value)}
      name="address"
      placeholder="Address"
    />
  );
};

Maintenant, au chargement de la page, notre promesse fetchAddress est exécutée dès lors que Step2 est instancié, et on retrouve la valeur résolue affichée dans notre input.

Conclusion

Ce tout nouveau composant Activity va simplifier certains cas complexes que l'on pouvait rencontrer jusqu'à présent dans nos applications. Son utilisation est très intuitive, mais nécessitera toutefois un peu de refactorisation dans les projets existants, notamment par rapport à la modification du comportement des effects.

Une idée de projet React, besoin d'accompagnement ? N'hésitez pas à nous contacter !

Ressources:

• Documentation officielle Activity

Dans cet article, je vous propose de voir comment mettre en place ces animations — et surtout, pourquoi on a choisi cet outil plutôt qu’un autre.

Qu'est-ce que Rive App ?

Rive est un outil de création d’animations vectorielles interactives. Là où d’autres génèrent des vidéos ou des gifs, Rive produit des fichiers .riv, très légers, qui peuvent réagir aux actions de l’utilisateur.

Les avantages de Rive App

Rive App a plusieurs avantages :

• Animations interactives : vos animations peuvent changer d'état selon les interactions utilisateur (clics, survols, données dynamiques)
• Fichiers ultra-légers : les animations Rive sont des fichiers vectoriels optimisés, bien plus petits que des vidéos équivalentes ou des gifs
• Multi-plateforme : une seule animation fonctionne sur Web ou mobile grâce aux différents runtimes (et bien entendu React / React Native)
• État dynamique : possibilité de créer des state machines complexes avec conditions et transitions et faire du data-binding

Pourquoi choisir Rive plutôt que Lottie ou des animations CSS ?

Rive se distingue par sa capacité à créer des animations véritablement interactives. Là où Lottie se limite à des animations linéaires et le CSS pour des transitions simples, Rive permet de créer des expériences où l'animation évolue en fonction du contexte applicatif.

Pour les anciens, Rive se rapproche de Flash, qui était un outil de création d’animations vectorielles interactives.

Deux modes, une interface

L’interface de Rive est découpée en deux parties : Design et Animation. Une pour préparer les assets, l’autre pour leur donner vie !

Je vous propose de détailler l'animation d'un élément de notre estimateur web et mobile.

Étape 1 : préparer le terrain

On commence par importer notre illustration (préparée dans Figma), et on isole chaque élément sur un calque séparé. Cette étape est un peu fastidieuse mais cruciale. Un calque = un élément animable. Sans ça, on se prend vite les pieds dans le tapis.

Voici mon illustration préparée avec chaque élément isolé, visible dans le panel de gauche Hierarchy :

Étape 2 : mode animation

Une fois l’illustration prête, on passe en mode animation grâce au switch en haut à droite de l'interface.

C’est là que les timelines, state machines et interpolations entrent en scène. Les animations avec Rive app se basent sur des timelines d'interpolation de propriétés (position, opacité, coordonnées, etc.) assez semblables aux interfaces de motion design comme After Effects.

Prenons l’exemple d’un élément que l’on veut faire apparaître dynamiquement : ici, une paire de guillemets en haut à droite de l’illustration.

On commence par créer un input de type boolean dans la state machine : has_blog. Il est à false par défaut, et c’est notre code React que nous écrirons plus tard qui viendra le passer à true :

On peut maintenant passer à l'animation !

On crée une nouvelle timeline dédiée à cette animation sur laquelle on va interpoler deux propriétés : position et opacité.

Ce n'est pas du Miyazaki mais suffisant pour donner un effet vivant à notre élément :

Mettre en place la state machine

Une fois l'animation créée, on peut maintenant créer notre state machine spécifique à cette animation.

Les states machines Rive permettent de gérer l'état de l'animation en fonction de conditions. Ici, on va créer deux états : l'animation qui se joue et l'animation qui disparaît (si l'utilisateur décoche l'option).

Pour l'animation de disparition, j'ai utilisé une astuce qui permet de jouer l'animation dans le sens inverse (notez le speed -1 dans le panel en bas à droite) :

Il ne reste plus qu'à ajouter mes conditions qui permettent de passer d'un état à l'autre simplement basé sur ma condition has_blog :

L'animation est maintenant prête ! Chaque animation de notre estimateur repose sur ce même pattern. C’est un peu répétitif, mais le résultat final vaut l’investissement.

Intégrer votre animation Rive dans React

On peut maintenant intégrer notre animation dans notre code React. Pour cela on peut utiliser le runtime React officiel de Rive.

Avant toute chose, il vous faut exporter votre animation au format .riv afin de le passer au composant <Rive/> :

export const App = () => {
  // Configuration de l'animation Rive
  const { rive, RiveComponent } = useRive({
    src: '/animations/estimator.riv', // Chemin vers votre fichier .riv
    artboard: 'web', // Nom de l'artboard à utiliser
    stateMachines: 'state_machine', // Nom de la state machine
    autoplay: true, // Démarre automatiquement l'animation
  })

  // Récupération de l'input de la state machine
  const hasBlog = useStateMachineInput(rive, 'state_machine', 'has_blog')

  return (
    <>
      <RiveComponent />
      <button onClick={() => (hasBlog.value = true)}>Afficher l'animation Blog</button>
    </>
  )
}

Voici une petite explication du code :

• useRive : ce hook configure et initialise votre animation Rive. Il retourne l'instance rive et le composant RiveComponent à afficher.

• useStateMachineInput : ce hook permet de récupérer et manipuler les inputs de votre state machine. Ici, on récupère l'input has_blog qu'on avait configuré dans Rive app.

• Interaction : en cliquant sur le bouton, on modifie la valeur de hasBlog.value à true, ce qui déclenche l'animation dans Rive.

Votre animation est ainsi prête à être utilisée dans votre application !

En résumé

Rive permettet d'apporter un supplément d'âme à vos projets, sans sacrifier la performance. Son modèle basé sur des state machines permet de créer des comportements fins, réactifs et parfaitement intégrés à nos apps.

L'intégration avec React est fluide, sans friction. Et surtout, elle garde les responsabilités bien séparées : Rive pour l’animation, React pour le déclenchement.

C’est un outil qu’on adopte rapidement une fois qu’on a mis les mains dedans. Mon conseil : commencez simple et explorez petit à petit.

Voici quelques use cases concrets :

• Animer des éléments d'une interface comme notre estimateur Web et mobile
• Intégrer des animations dans une application React Native (écran de onboarding, etc.)
• Créer des apps à part entière (jeux, etc.)
• Créer des layouts interactifs pour des streaming videos (via OBS, etc.)

Si vous avez des projets qui nécessitent des animations interactives, n'hésitez pas à nous contacter, nous serons ravis de vous accompagner dans la mise en place de Rive app.

Enfin, vous pouvez jouer avec nos estimateurs Web et mobile ici.

Ressources utiles :

• Documentation officielle Rive app
• Runtime React

👋

Plus récemment, NativeWind a prit aussi beaucoup en popularité, profitant d'une certaine standardisation de l'utilisation de Tailwind côté web. Simple à configurer, avec une API quasi identique à celle de Tailwind, il est assez simple pour un développeur Web de se lancer dans la création d'une application React Native avec NativeWind. Néanmoins, son fonctionnement interne n'est pas toujours évident à comprendre et demande parfois d'être assez verbeux quand il s'agit de créer des composants très génériques (via l'utilisation de remapProps ou cssInterop par exemple).

C'est dans ce contexte de course à la performance et à la meilleure DX qu'Unistyles a sorti sa version 3, dont nous allons dans cet article explorer les fonctionnalités et les avantages de cette librairie.

Comment ça marche ?

Unistyles a pour vocation de fournir une API très proche de l'API StyleSheet de React Native, tout en y ajoutant des fonctionnalités supplémentaires comme la gestion de thème, le support des breakpoints, l'ajout de variants. Pour aller plus loin, Unistyles ajoute un aspect performance en gérant les styles directement au sein de la partie C++ de l'application. Concrètement, cela permet d'associer un style à un noeud natif de notre arbre de composants, et de faire en sorte que ce noeud réagisse aux changements de style qui peuvent se produire (changement de thème, propriété dépendante du viewport, etc.), le tout sans provoquer de re-rendu de notre arbre de composants côté JavaScript. Toutes ces optimisations sont orchestrées par un plugin Babel.

Utilisation

Explorons Unistyles en créant un projet Expo. Nous utiliserons le template "Blank" :

bun create expo-app demo-unistyles -t
cd demo-unistyles
npx expo install react-native-unistyles react-native-nitro-modules react-native-reanimated react-native-edge-to-edge

Ajoutons le plugin Babel :

npx expo customize babel.config.js

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: [
      [
        "react-native-unistyles/plugin",
        {
          root: "src", // Dossier racine contenant les composants stylisés
        },
      ],
    ],
  };
};

Créons maintenant un style très simple dans le composant App :

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#FFFFFF',
  },
});

const App = () => {
  return <View style={styles.container} />
}

export default App;

On constate finalement que, en l'état, l'API de Unistyles offre une parité 1:1 avec l'API StyleSheet de React Native, rendant ainsi une migration vers Unistyles très simple.

Theming

Nous allons maintenant utiliser ce qui est un atout d'Unistyles par rapport à StyleSheet : la possibilité de définir des thèmes.

Créons un fichier src/themes.ts :

// Quelques utilitaires
const spacing = (size: number) => size * 4;
const radius = (size: number) => size * 4;

const utils = {
  spacing,
  radius,
};

export const light = {
  colors: {
    primary: "#007AFF",
    red: "#ed3e3e",
    background: "#ffffff",
  },
  utils,
};

export const dark = {
  colors: {
    primary: "#4da6ff",
    red: "#fa645c",
    background: "#3E3E3E",
  },
  utils,
};

StyleSheet.configure({
  themes: {
    light,
    dark,
  },
  settings: {
    /**
     * L'utilisation de thèmes nommés "dark" et "light" permet de les utiliser en fonction
     * du thème utilisé par le système d'exploitation. Pour cela, il faut s'assurer que
     * la propriété `userInterfaceStyle` de la configuration Expo soit définie en "automatic".
     */
    adaptiveThemes: true,
  },
});

type AppThemes = {
  light: typeof light;
  dark: typeof dark;
};

declare module "react-native-unistyles" {
  export interface UnistylesThemes extends AppThemes {}
}

Nous avons ici défini 2 thèmes de couleur différent, chacun destiné à s'adapter selon le thème du système d'exploitation. Il est évidemment possible de définir d'autres thèmes avec des noms différents. Pour que ces thèmes soient bien pris en compte avant le premier rendu, il est impératif d'importer ce fichier dans notre index.ts :

registerRootComponent(App);

Faisons maintenant usage de ces thèmes. Pour ce faire, il va falloir transformer légèrement notre fonction StyleSheet.create. Celle-ci prendra maintenant en paramètre une fonction recevant 2 arguments : le thème actuel et des variables de styling liées à l'appareil (nous aborderons cela plus tard).

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: theme.colors.background,
    padding: theme.utils.spacing(4)
  },
}));

const App = () => {
  return <View style={styles.container} />
}

export default App;

Si nous alternons entre le light et dark mode sur notre appareil, nous verrons la couleur de fond changer, le tout sans que notre arbre de composants React ne soit re-rendu !

Responsive

Il est possible de définir des styles selon la taille ou l'orientation de l'appareil. Par défaut, Unistyles fournit la possibilité de fournir des styles selon des breakpoints liés à l'orientation, mais il est tout à fait possible de définir nos propres breakpoints liés à la taille de l'écran. Essayons par exemple de changer la couleur de fond en fonction de l'orientation :

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: {
      portrait: theme.colors.background,
      landscape: theme.colors.primary,
    },
    padding: theme.utils.spacing(4)
  },
}));

const App = () => {
  return <View style={styles.container} />
}

export default App;

Maintenant, lorsque nous changeons l'orientation de notre appareil, la couleur de fond change, toujours sans provoquer de re-rendu !

Runtime Unistyles

Évoquons maintenant le sujet du runtime que l'on a vu précédemment. Unistyles expose des variables de runtime, qui sont des valeurs purement liées à l'appareil et qui sont accessibles à tout moment. Il existe 2 types de runtime :

• le runtime global, exposant des variables accessibles à tout moment, mais aussi des fonctions permettant d'altérer certains aspects comme le thème utilisé, le contenu du thème, la couleur de fond de notre vue native, etc.
• le runtime de style, appelé mini runtime, qui lui aussi expose des variables similaires à celles du runtime global, mais qui ont pour but d'être utilisées dans les styles. Ainsi, nos styles seront réactifs aux changements de valeurs de ces variables.

Faisons usage du mini runtime pour ajouter un espacement en haut de notre vue en fonction de la safe area :

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: {
      portrait: theme.colors.background,
      landscape: theme.colors.primary,
    },
    padding: theme.utils.spacing(4),
    paddingTop: rt.insets.top,
  },
}));

const App = () => {
  return <View style={styles.container} />
}

export default App;

Variants

À la manière de Tamagui et de bien d'autres librairies de style, Unistyles permet d'ajouter des variants pour un style précis. Un cas d'utilisation parfait pour cela est la création d'un bouton. Pour un aspect plus joli, nous allons même nous permettre d'animer la couleur du bouton quand un changement de couleur est détecté.

  Pressable,
  type PressableProps,
  StyleProp,
  Text,
  ViewStyle,
} from "react-native";

  useAnimatedStyle,
  withTiming,
} from "react-native-reanimated";



type Props = UnistylesVariants<typeof styles> &
  Omit<PressableProps, "style"> & {
    label: string;
    style?: StyleProp<ViewStyle>;
  };

const Button = ({
  type = "primary",
  style,
  label,
  children,
  ...props
}: Props) => {
  // Activation du variant pour le composant Button
  styles.useVariants({ type });
  // Récupération de la couleur de fond sous forme de shared value
  const color = useAnimatedVariantColor(styles.container, "backgroundColor");
  // Animation de la couleur de fond
  const animatedStyle = useAnimatedStyle(() => {
    return {
      backgroundColor: withTiming(color.value, { duration: 500 }),
    };
  });

  return (
    <Pressable {...props}>
      <Animated.View style={[styles.container, animatedStyle, style]}>
        <ButtonText type={type}>{label}</ButtonText>
      </Animated.View>
    </Pressable>
  );
};

const ButtonText = ({
  children,
  type,
}: PropsWithChildren<UnistylesVariants<typeof styles>>) => {
  // Activation du variant pour le composant ButtonText
  styles.useVariants({ type });

  return <Text style={styles.text}>{children}</Text>;
};

export default Button;

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    borderRadius: theme.utils.radius(2),
    flexDirection: "row",
    paddingHorizontal: theme.utils.spacing(4),
    paddingVertical: theme.utils.spacing(3),

    variants: {
      type: {
        primary: {
          backgroundColor: theme.colors.primary,
        },
        destructive: {
          backgroundColor: theme.colors.red,
        },
      },
    },
  },
  text: {
    fontSize: 14,
    variants: {
      type: {
        primary: {
          color: "white",
        },
        destructive: {
          color: "white",
        },
      },
    },
  },
}));

Nous avons défini ici 2 variants pour nos boutons. Ces variants peuvent être passé en props de notre composant Button.

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: {
      portrait: theme.colors.background,
      landscape: theme.colors.primary,
    },
    padding: theme.utils.spacing(4),
    paddingTop: rt.insets.top,
    gap: theme.utils.spacing(4),
  },
}));

const App = () => {
  return (
    <View style={styles.container}>
      <Button type="primary" label="Primary Button" />
      <Button type="destructive" label="Destructive Button" />
    </View>
  )
}

export default App;

Profitons-en pour faire usage du runtime global. Nous allons faire en sorte que nos boutons changent le thème de couleur utilisé.

const styles = StyleSheet.create((theme, rt) => ({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: {
      portrait: theme.colors.background,
      landscape: theme.colors.primary,
    },
    padding: theme.utils.spacing(4),
    paddingTop: rt.insets.top,
    gap: theme.utils.spacing(4),
  },
}));

const App = () => {
  return (
    <View style={styles.container}>
      <Button type="primary" label="Light mode" onPress={() => UnistylesRuntime.setTheme('light')} />
      <Button type="destructive" label="Dark mode" onPress={() => UnistylesRuntime.setTheme('dark')} />
    </View>
  )
}

export default App;

Maintenant au clic sur les boutons, leur couleur de fond change, encore une fois sans provoquer de re-rendu.

En plus des variants, Unistyles offre la possibilité d'ajouter des styles selon les valeurs de plusieurs variants : les variants composés.

Conclusion

Unistyles est une alternative très intéressante aux solutions existantes, de part son aspect performance, sa simplicité d'utilisation et ses similitudes avec l'API StyleSheet. À noter qu'un support Web est lui aussi disponible. Que choisir entre Unistyles et Tamagui ? Le choix est discutable mais de part sa facilité de configuration, Unistyles me semble être un bon choix. Si toutefois vous êtes un grand fan de Tailwind, le créateur d'Unistyles a créé Uniwind (pas encore sorti à l'heure de l'écriture de cet article), ayant pour but de combiner les performances de Unistyles avec les avantages de Tailwind.

Des idées de projet en React Native, une envie de migrer votre application vers Unistyles ? N'hésitez pas à nous contacter !

Model Context Protocol (MCP)

Model Context Protocol (MCP) est un standard de communication permettant de fournir un contexte à un LLM. En tant que développeur, vous êtes probablement familier avec MCP si vous utilisez un IDE supportant les agents IA (Cursor, Zed, etc.). Un serveur implémentant MCP peut fournir plusieurs types de données :

• un ensemble de tools à exécuter
• des prompts prédéfinis
• des données précises venant d'une source externe (BDD, API, etc.)

En réalité, l'usage le plus courant est d'utiliser les tools exposés par le serveur MCP.

Ce serveur peut ensuite être exposé soit via une URL, soit un exécutable.

Implémentation

Nous allons créer une petite application Next.js utilisant un MCP Postgres. Le but est de pouvoir répondre à une requête dans un langage naturel puis d'afficher les informations issues de la base de données.

bun create next-app

Installons les dépendances nécessaires :

bun add ai @ai-sdk/anthropic @modelcontextprotocol/sdk pg react-markdown

Implémentation du serveur MCP

Pour le serveur MCP, nous allons réutiliser le serveur Zed Postgres, que nous allons légèrement modifier.

  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";


const { server } = new McpServer(
  {
    name: "postgres",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

const stdioTransport = new StdioServerTransport();

On initialise ici un serveur MCP qui sera en capacité d'exposer uniquement les données liées aux tools. D'autre types de capabilities sont disponibles: resources, prompts, completions. Nous utiliserons notre MCP sous forme d'exécutable. Par conséquent, la communication s'effectuera via la lecture et l'écriture sur stdin et stdout, d'où l'utilisation du transport StdioServerTransport. Si l'on souhaite utiliser le transport HTTP, nous devront utiliser StreamableHTTPClientTransport, et exposer notre serveur MCP à un port, en utilisant express par exemple.

const dbUrl = Bun.env.PG_URL;
const resourceBaseUrl = new URL(dbUrl!);
resourceBaseUrl.protocol = "postgres:";
resourceBaseUrl.password = "";

const pool = new pg.Pool({
  connectionString: Bun.env.PG_URL,
});

On initialise maintenant notre instance Postgres, afin d'établir une connexion plus tard.

Définissons maintenant l'accès à nos tools. Dans un premier temps nous devons en exposer la liste :

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "pg-schema",
        description: "Returns the schema for a Postgres database.",
        inputSchema: {
          type: "object",
          properties: {
            mode: {
              type: "string",
              enum: ["all", "specific"],
              description: "Mode of schema retrieval",
            },
            tableName: {
              type: "string",
              description:
                "Name of the specific table (required if mode is 'specific')",
            },
          },
          required: ["mode"],
          if: {
            properties: { mode: { const: "specific" } },
          },
          then: {
            required: ["tableName"],
          },
        },
      },
      {
        name: "query",
        description: "Run a read-only SQL query",
        inputSchema: {
          type: "object",
          properties: {
            sql: { type: "string" },
          },
        },
      },
    ],
  };
});

ListToolsRequestSchema est un schéma Zod. Si le serveur MCP reçoit une requête correspondant à ce schéma, alors il doit exécuter la fonction passée en second argument. Cette fonction doit retourner une liste de tools contenant un nom (servant d'identifiant théoriquement unique), une description qui sera lue par le modèle ainsi qu'un JSON Schema permettant d'indiquer au modèle la structure de donnée attendue pour l'exécution du tool.

Maintenant pour l'exécution de nos tools :

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "pg-schema") {
    const mode = request.params.arguments?.mode;

    const tableName = (() => {
      switch (mode) {
        case "specific": {
          const tableName = request.params.arguments?.tableName;

          if (typeof tableName !== "string" || tableName.length === 0) {
            throw new Error(`Invalid tableName: ${tableName}`);
          }

          return tableName;
        }
        case "all": {
          return ALL_TABLES;
        }
        default:
          throw new Error(`Invalid mode: ${mode}`);
      }
    })();

    const client = await pool.connect();

    try {
      const sql = await getSchema(client, tableName);

      return {
        content: [{ type: "text", text: sql }],
      };
    } finally {
      client.release();
    }
  }

  if (request.params.name === "query") {
    const sql = request.params.arguments?.sql as string;

    const client = await pool.connect();
    try {
      await client.query("BEGIN TRANSACTION READ ONLY");
      // Force a prepared statement: Prevents multiple statements in the same query.
      // Name is unique per session, but we use a single session per query.
      const result = await client.query({
        name: "sandboxed-statement",
        text: sql,
        values: [],
      });
      return {
        content: [
          { type: "text", text: JSON.stringify(result.rows, undefined, 2) },
        ],
      };
    } finally {
      client
        .query("ROLLBACK")
        .catch((error) =>
          console.warn("Could not roll back transaction:", error),
        );

      // Destroy session to clean up resources.
      client.release(true);
    }
  }

  throw new Error("Tool not found");
});

/**
 * @param tableNameOrAll {string}
 */
async function getSchema(client, tableNameOrAll) {
  const select =
    "SELECT column_name, data_type, is_nullable, column_default, table_name FROM information_schema.columns";

  let result;
  if (tableNameOrAll === ALL_TABLES) {
    result = await client.query(
      `${select} WHERE table_schema NOT IN ('pg_catalog', 'information_schema')`,
    );
  } else {
    result = await client.query(`${select} WHERE table_name = $1`, [
      tableNameOrAll,
    ]);
  }

  const allTableNames = Array.from(
    new Set(result.rows.map((row) => row.table_name).sort()),
  );

  let sql = "```sql\n";
  for (let i = 0, len = allTableNames.length; i < len; i++) {
    const tableName = allTableNames[i];
    if (i > 0) {
      sql += "\n";
    }

    sql += [
      `create table "${tableName}" (`,
      result.rows
        .filter((row) => row.table_name === tableName)
        .map((row) => {
          const notNull = row.is_nullable === "NO" ? "" : " not null";
          const defaultValue =
            row.column_default != null ? ` default ${row.column_default}` : "";
          return `    "${row.column_name}" ${row.data_type}${notNull}${defaultValue}`;
        })
        .join(",\n"),
      ");",
    ].join("\n");
    sql += "\n";
  }
  sql += "```";

  return sql;
}

De la même manière que pour lister les tools, nous avons le schéma CallToolRequestSchema pour intercepter la requête de leur exécution.

On peut maintenant démarrer notre serveur :

const main = async () => {
  await server.connect(stdioTransport);

  // Dans le cas d'un transport HTTP
  // app.post("/mcp", async (req, res) => {
  //   await transport.handleRequest(req, res);
  // });

  // app.listen(Number(Bun.env.PORT ?? 3001));
};

main();

Implémentation Next (Client)

Créons maintenant notre page sur notre application Next.js, en utilisant le SDK AI de Vercel :

"use client";



export default function HomePage() {
  const { messages, input, handleInputChange, handleSubmit } = useChat();

  return (
    <div className="flex flex-col h-screen max-w-4xl mx-auto p-4">
      <div className="flex-1 overflow-y-auto mb-4">
        {messages.map((message, index) => (
          <div
            key={index}
            className={`mb-4 p-3 rounded-lg ${
              message.role === "user" ? "bg-blue-100 ml-8" : "bg-gray-100 mr-8"
            }`}
          >
            <div className="font-semibold text-sm text-gray-600 mb-1">
              {message.role === "user" ? "You" : "Assistant"}
            </div>
            <div className="text-gray-800">
              <Markdown>{message.content}</Markdown>
            </div>
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type your message..."
          className="flex-1 px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500"
        />
        <button
          type="submit"
          className="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500"
        >
          Send
        </button>
      </form>
    </div>
  );
}

Implémentation Next (Serveur)

Créons maintenant notre route API /api/chat, utilisée par le hook useChat.

export async function POST(req: NextRequest) {
  const { messages } = await req.json();
  const mcpTransport = new Experimental_StdioMCPTransport({
    command: "bun",
    args: ["pg:mcp"],
  });

  const mcpClient = await experimental_createMCPClient({
    transport: mcpTransport,
    name: "postgres-mcp-client",
  });

  try {
    const tools = await mcpClient.tools();

    const result = streamText({
      model: anthropic("claude-4-sonnet-20250514"),
      messages,
      tools,
      maxSteps: 3,
      onError: async (error) => {
        await mcpClient.close();
      },
      onFinish: async () => {
        await mcpClient.close();
      },
    });

    return result.toDataStreamResponse();
  } catch (error) {
    console.error("Error:", error);
  }
}

Le SDK AI fournit des outils actuellement au stade expérimental permettant d'intéragir avec des serveurs MCP et d'en récupérer les tools.

const mcpTransport = new Experimental_StdioMCPTransport({
  command: 'bun',
  args: ['pg:mcp'],
})

const mcpClient = await experimental_createMCPClient({
  transport: mcpTransport,
  name: 'postgres-mcp-client',
})

Ici on crée un transport lié à notre sortie standard utilisée par le binaire de notre serveur MCP. Ce binaire est exécuté via la commande bun pg:mcp que nous avons définie dans notre package.json :

"pg:mcp": "dotenv -e .env -- bun ./mcp-server.ts"

L'appel à mcpClient.tools() renvoie une liste de tools compatible avec les API de tools du SDK AI, avec le bon nom, la bonne description, les bons paramètres, ainsi qu'une fonction d'exécution. Il est bien évidemment possible de se brancher à plusieurs serveurs MCP en même temps et d'en combiner les tools. Toutefois, il faut faire attention aux potentielles collisions qui peuvent survenir pour les noms de chacun. La propriété maxSteps: 3 permet de continuer l'exécution de notre stream après l'appel à un tool. Par défaut, cette valeur est de 1. Ici on l'a définie à 3 pour permettre à nos tools de récupération du schéma et d'exécution de requêtes SQL d'être bien exécutés et renvoyés au client.

Testons maintenant l'ensemble ! Lançons notre serveur de développement Next :

bun dev

Puis rendons-nous sur http://localhost:3000 pour voir notre application en action. Une page avec un simple champ de saisie en bas apparait. Dans mon cas, je choisis de faire la demande suivante :

Donne moi la liste des 5 premiers email d'utilisateurs de ma base de données

Le LLM a bien été capable de me sortir des données dont elle n'a, de base, pas connaissance, tout ça grâce à l'utilisations de tools récupérés depuis notre serveur MCP.

Conclusion

MCP a en quelques sortes révolutionné notre manière d'utiliser les LLMs. Leur capacité de s'interfacer entre les modèles et des API tierces rend l'accès aux données encore plus puissant qu'il ne l'était déjà. Ainsi on peut imaginer des cas d'utilisation sur des back-offices par exemple, simplifiant l'aggrégation de données provenant de sources multiples, le tout à partir d'une simple requête dans un language naturel. Les serveurs MCP peuvent aussi être installés sur des clients qui les supportent, par exemples les IDE mais aussi les applications de LLM (Claude, Chat GPT). Une liste très exhaustive de serveurs est disponible sur mcp.so, et vous trouverez surement le MCP qui répond à vos besoins.

Vous souhaitez implémenter un serveur MCP pour votre application ? N'hésitez pas à nous contacter !

Grâce à la popularité de ChatGPT, tout le monde connaît désormais cette interface en mode chat. Elle est simple à prendre en main, naturelle pour l'utilisateur, et c'est devenu un standard.

Chez Premier Octet, on s'appuie sur le Vercel AI SDK pour développer ce type d'interface. C'est l'état de l'art pour créer des expériences réactives, élégantes, avec un support natif du streaming des réponses et du tool calling (on y revient juste après).

Qu'est-ce qu'un agent IA ?

Un agent IA, c'est tout simplement une interface qui peut comprendre vos demandes en langage naturel et agir en conséquence. Contrairement à un chatbot classique avec des réponses préprogrammées, l'agent peut analyser le contexte, prendre des décisions et utiliser des outils pour accomplir des tâches concrètes.

Concrètement, l'agent peut tourner avec différents modèles de langage : GPT (OpenAI), Claude (Anthropic), Mistral, Gemini… On se connecte à leur API et on garde la liberté de personnaliser l'interface pour coller à l'identité de nos clients.

Pour rendre cet agent vraiment utile, il y a deux façons principales de le connecter à vos données métiers.

Et bonne nouvelle : elles sont complémentaires.

Connecter l'agent à vos données métiers

La boite à outils

La première approche consiste à donner des outils à l'agent. C'est ce qui va lui permettre d'agir : consulter une commande, chercher un bien immobilier, créer un ticket, ajouter un produit au panier…

Concrètement, comment ça marche ?

On commence par définir ensemble ce que l'agent doit savoir faire. Ensuite, on développe la "boîte à outils" sur mesure, que le modèle pourra appeler selon les besoins exprimés dans la conversation.

Chaque outil a un contrat clair : il attend certains paramètres (certains obligatoires, d'autres optionnels), et il renvoie une réponse structurée.

Prenons l'exemple d'un outil permetant de lancer une recherche d'annonces immobilières. Cet outil attend au minimum :

• un lieu
• une surface minimale
• un budget maximum

Si l'utilisateur ne donne pas toutes les infos d'emblée, l'agent va naturellement poser les questions manquantes. Une fois les critères réunis, il déclenche l'outil, qui interroge votre API ou base de données. L'agent interprète la réponse et répond dans la foulée.

On a alors deux options :

• Soit on reste dans le chat pur : l'agent répond avec du texte, qu'on peut formater, styliser, cadrer.
• Soit on va plus loin avec des widgets personnalisés dans le flux du chat : par exemple des cards reprenant l'UI du site, avec les annonces directement affichées.

Cette combinaison de langage naturel et de widgets métiers permet d'avoir une expérience utilisateur moderne, fluide, et surtout utile.

Et évidemment, on peut aller très loin : prise de rendez-vous, ajout au panier, paiement, génération de documents… C'est une interface conversationnelle sur mesure.

Transmettre de la connaissance métier

La deuxième approche consiste à enrichir l'agent avec du savoir métier.

On parle ici de RAG (Retrieval-Augmented Generation). Pour résumé, on vectorise votre contenu (FAQ, fiches produits, documentation…) pour qu'il devienne compréhensible par le modèle de langage.

Une fois vectorisé, l'agent pourra répondre à des questions précises sur vos services, vos produits, vos conditions générales, etc., avec un niveau de détail et de pertinence qui dépasse les simples modèles "out of the box".

Si vous souhaitez approfondir le sujet du RAG, je vous invite à lire notre article sur le sujet.

Ces deux approches sont bien sûr complémentaires. Elles permettent de couvrir des cas d'usage différents :

• un agent IA avec des outils pour interagir avec vos services
• un agent IA avec du savoir métier pour répondre à des questions précises

C'est souvent la combinaison de ces deux approches qui permet de couvrir la majorité des besoins.

Et le timing dans tout ça ?

C'est souvent la question qui suit : combien de temps faut-il pour mettre ça en place ?

5 à 10 jours suffisent pour une première version fonctionnelle, intégrée à votre site, avec une interface sur mesure et quelques outils bien choisis.

On commence par cadrer ensemble : quelles capacités ? quels outils ? quelles données ? Une fois les specs définies, on développe, on teste, on connecte. Et on laisse l'IA faire sa part.

Et le coût d'utilisation ?

L'agent repose sur une API tierce (OpenAI, Anthropic, Mistral…). Ces APIs sont aujourd'hui accessibles et scalables. À titre d'exemple, voici les tarifs de l'API OpenAI GPT-4 Mini (en juin 2025) :

• 0,40 $ / million de tokens en entrée
• 1,60 $ / million de tokens en sortie

Pour une session de 10 échanges (Q/R), on parle généralement de moins d'un centime.

Il est aussi possible d'auto-héberger un modèle open source, mais cela nécessite une machine avec GPU. On peut aussi passer par des APIs sur étagères comme le propose OVH si l'on souhaite garder un contrôle total sur les données.

En résumé

Créer un agent IA pour votre site n'est plus un sujet "futuriste" ou "expérimental". C'est concret, rapide à mettre en place, et surtout utile.

C'est aussi souvent une première brique pour aller plus loin ensuite : classification de contenu, génération de texte, aide à la rédaction, automatisation de tâches internes, génération de documents et assets…

Envie de tenter l'expérience ?

Chez Premier Octet, on vous accompagne pour concevoir un agent IA aligné avec vos besoins, intégré à votre site, connecté à vos données.

Contactez-nous si vous avez envie d'en discuter ou si vous avez déjà une idée d'usage. On vous aide à la concrétiser en quelques jours.

👋

Présentation technique

Start, créé par Tanner Linsley que l'on ne présente plus, possède un routing basé sur une librairie déjà existante, TanStack Router. Utilisable de base pour les SPA, Start l'intègre notamment pour effectuer du SSR, à la manière de ce que fait Remix avec React Router.

Côté bundling, Start se base sur Vite, nous permettant ainsi de bénéficier de tous les plugins Vite disponibles. Pour rappel, Next se base sur SWC ou TurboPack selon les versions.

Explorons plus en détails Start via une petite application toute simple avec une authentification basique, une liste de posts et les détails d'un post.

Exploration

Mise en place

Start propose un exemple de base à cloner faisant office de starter kit. Nous allons ici mettre en place un projet en partant de zéro, utilisant Tailwind CSS.

mkdir starter-example
cd starter-example
yarn init -y

Installons maintenant les dépendances :

yarn add @tanstack/react-start @tanstack/react-router react react-dom zod
yarn add -D vite @vitejs/plugin-react typescript @types/react @types/react-dom tailwindcss @tailwindcss/vite

Mettons en place nos différents fichiers de configuration :

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "skipLibCheck": true,
    "strictNullChecks": true,
  },
}

export default defineConfig({
    plugins: [
      tanstackStart(),
      tailwindcss()
    ],
  },
})

Mettons à jour les scripts de notre package.json :

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  }
}

Créons maintenant notre points d'entrée requis par Start. Celui-ci se situera dans le dossier src à la racine du projet.

export function createRouter() {
    const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
    /*
        * il est ici possible de configurer les options par défaut du routeur,
        * comme par exemple le composant par défaut pour les routes en not found,
        */
    })

    return router

}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof createRouter>
  }
}

Créons notre feuille de style CSS pour Tailwind :

@import "tailwindcss";

Créons maintenant notre document HTML principal. C'est l'équivalent du fichier layout.tsx à la racine du dossier app d'une application Next. Ce fichier ce situe dans un sous-dossier routes. C'est dans ce sous-dossier que ce situeront toutes les routes de notre application.

  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
// import de la feuille de style au format URL


export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "Start Example",
      },
    ],
    links: [
      {
        rel: "stylesheet",
        href: appCss,
      },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body className="bg-white dark:bg-slate-900">
        <div className="min-h-screen flex flex-col">{children}</div>
        <Scripts />
      </body>
    </html>
  );
}

Le composant Outlet est un composant très utile pour construire des layouts imbriqués. Celui-ci rend le contenu de la route active et peut être utilisé à d'autres endroits de l'application. Nous verrons un cas d'utilisation plus tard.

Nous pouvons maintenant exécuter yarn dev pour démarrer notre bundler.

Notre première route

Créons un fichier src/routes/index.tsx pour notre première route. Si vous avez votre bundler d'ouvert, vous constaterez une fonctionnalité très intéressante venant de TanStack Router : un template de base pour le fichier avec tout le contenu nécessaire est généré. Celui-ci change en fonction du chemin du fichier. Par exemple, renommer le fichier changera le chemin de la route.

export const Route = createFileRoute("/")({
  component: Home,
});

function Home() {
  return (
    <form
      className="flex flex-1 flex-col justify-center items-center gap-4"
    >
      <div className="flex flex-col gap-2">
        <label htmlFor="username" className="dark:text-white">
          Username
        </label>
        <input
          name="username"
          id="username"
          placeholder="Username"
          className="dark:text-white border dark:border-white"
        />
        <label htmlFor="password" className="dark:text-white">
          Password
        </label>
        <input
          name="password"
          id="password"
          placeholder="Password"
          type="password"
          className="dark:text-white border dark:border-white"
        />
      </div>
      <button
        type="submit"
        className="bg-blue-500 px-4 py-3 rounded-md text-white cursor-pointer"
      >
        Login
      </button>
    </form>
  );
}

En se rendant sur http://localhost:3000, notre page formulaire s'affiche correctement !

Mettons maintenant en place notre seconde route, qui sera notre liste de posts. Cette route devra être plus tard protégée par une authentification.

export const Route = createFileRoute('/posts')({
  component: RouteComponent,
  loader: () => {
    return loadPosts()
  },
})

function RouteComponent() {
const loadedPosts = Route.useLoaderData();

return (

<div className="flex flex-1 justify-center items-center">
  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
    {loadedPosts.map((post) => (
      <PostCard key={post.id} title={post.title} content={post.content} id={post.id} />
    ))}
  </div>
</div>
); }

type Props = {
  title: string;
  content: string;
  id: number;
};

const PostCard = ({ title, content, id }: Props) => {
  return (
    <Link
      to="/posts/$id"
      // Prefetch de la page au hover
      preload="intent"
      params={{ id: id.toString() }}
      className="bg-white shadow-md rounded-lg p-6 mb-6 dark:shadow-white hover:scale-[101%] transition-transform duration-300 cursor-pointer"
    >
      <h2 className="text-2xl font-bold mb-4">{title}</h2>
      <p className="text-gray-700 line-clamp-3 text-ellipsis">{content}</p>
    </Link>
  );
};

export default PostCard;

Ici on retrouve une API assez similaire à celle de Remix pour charger de la donnée côté serveur :

• loader est exécuté au chargement de la page et renvoie notre donnée
• on récupère cette donnée via le hook useLoaderData accessible depuis notre objet Route.

Ici, notre liste de posts est chargée depuis une fonction serveur, l'opportunité de faire la connaissance avec les server functions de Start.

Server functions

Les server functions sont, comme celles de React et Next, des fonctions appelées depuis n'importe où (sauf les routes API) et exécutées côté serveur. Les server functions de Start ont toutefois des fonctionnalités en plus par rapport à ce que l'on retrouve par exemple sur Next :

• possibilité de définir la méthode HTTP à utiliser (POST ou GET)
• ajout de validation (via zod par exemple)
• accès à l'ensemble de la requête HTTP
• possibilité de définir le type de réponse (JSON, stream)

Créons notre fonction loadPosts :

export const loadPosts = createServerFn()
  .handler((async) => {
    return posts;
  });

export const posts = Array.from({ length: 10 }, (_, i) => ({
  id: i + 1,
  title: "Lorem ipsum dolor sit amet.",
  content: '....lorem ipsum',
}));

Profitons-en pour créer notre fonction de login pour notre formulaire ! Chose très intéressante, Start propose une solution clé en main pour gérer les sessions, que ce soit via le session storage ou les cookies.

export const loginAction = createServerFn({
  method: 'POST',
})
  .validator((data: unknown) => {
    const schema = z.object({
      username: z.string().min(1),
      password: z.string().min(1),
    })

    const result = schema.safeParse(data)

    if (!result.success) {
      throw json({ error: result.error.issues, message: 'Validation failed' }, { status: 422 })
    }

    return result.data
  })
  .handler(async ({ data }) => {
    // Fake delay
    await setTimeout(1000)
    if (data.username !== 'admin' && data.password !== 'admin') {
      setResponseStatus(401)
      return {
        success: false,
        error: 'Unauthorized',
      }
    }

    const session = await useAppSession()

    await session.update({
      name: data.username,
    })

    // On redirige vers la page de posts après la connexion réussie
    throw redirect({
      to: '/posts',
    })
  })

export const logoutAction = createServerFn({ method: 'POST' }).handler(async () => {
  const session = await useAppSession()

  await session.clear()

  throw redirect({
    to: '/',
  })
})

type UserSession = {
  name: string
}

export const useAppSession = () => {
  return useSession<UserSession>({
    password: 'MyPasswordAsALongStringOfCharactersOfAtLeast32Characters',
    // On utilise les cookies, on peut configurer les options de cookie ici.
    // Par défaut, le session storage est utilisé.
    cookie: {},
  })
}

export const Route = createFileRoute('/')({
  component: Home,
})

function Home() {
  const login = useServerFn(loginAction)

  return (
    <form
      className="flex flex-1 flex-col justify-center items-center gap-4"
      onSubmit={async (e) => {
        e.preventDefault()
        const formData = new FormData(e.target as HTMLFormElement)
        const username = formData.get('username') as string
        const password = formData.get('password') as string
        login({ data: { username, password } })
      }}
    >
      <div className="flex flex-col gap-2">
        <label htmlFor="username" className="dark:text-white">
          Username
        </label>
        <input
          name="username"
          id="username"
          placeholder="Username"
          className="dark:text-white border dark:border-white"
        />
        <label htmlFor="password" className="dark:text-white">
          Password
        </label>
        <input
          name="password"
          id="password"
          placeholder="Password"
          type="password"
          className="dark:text-white border dark:border-white"
        />
      </div>
      <button type="submit" className="bg-blue-500 px-4 py-3 rounded-md text-white cursor-pointer">
        Login
      </button>
    </form>
  )
}

Et voilà, après la connexion, vous êtes maintenant redirigé vers la liste des posts !

Le concept de layout

Un layout a pour but de créer une structure statique dans laquelle va s'intégrer le contenu de notre route. Avec Next, nous créons un layout via une route layout.tsx au même niveau que la route. Start (via l'intermédiaire du Router) a une approche très similaire à React Router pour gérer les layouts. Tant qu'une partie de notre URL est matchée, alors sa route est rendue.

Par exemple :

• /posts -> <RootDocument><Posts>
• /posts/:id -> <RootDocument><Posts><Post>

Ce comportement est configurable en fonction du nom du fichier. Par conséquent, par défaut, une route comme /posts que l'on a créé peut agir comme un layout pour /posts/:id. Le contenu de /posts/:id sera affiché via le composant Outlet.

Il est aussi possible de faire en sorte de créer un layout qui n'est pas lié à une route. C'est ce que l'on appelle un pathless layout. Celui-ci aura un nom de fichier préfixé d'un _.

Créons un layout utilisé au sein de nos routes authentifiées :

export const Route = createFileRoute("/_app")({
  component: RouteComponent,
});

function RouteComponent() {
  const logout = useServerFn(logoutAction);

  return (
    <div className="flex flex-col flex-1">
      <nav className="flex items-center justify-end py-3 px-4">
        <ul>
          <li
            className="dark:text-white hover:underline cursor-pointer"
            onClick={() => {
              logout();
            }}
          >
            Logout
          </li>
        </ul>
      </nav>
      <div className="px-4">
        <Outlet />
      </div>
    </div>
  );
}

Nous devons maintenant déplacer notre route posts.tsx dans un sous dossier _app, correspondant au nom de notre layout. Évidemment, nous pouvons donner le nom que l'on veut à notre layout. Il faut simplement garder une correspondance entre le nom du fichier du layout et le dossier créé.

Notre liste de posts est maintenant bien intégré au sein de notre layout. Il est évidemment possible de nester les layouts à l'infini, c'est le composant Outlet qui se charge de rendre les routes enfant à l'emplacement désiré.

Nous pouvons maintenant, grâce au layout, prévenir l'accès à nos pages authentifiées. En effet, un pathless layout dispose des mêmes possibilités d'usage d'une route. On peut donc utiliser la propriété beforeLoad afin de vérifier la connexion de l'utilisateur.

  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";




const fetchUser = createServerFn({ method: "GET" }).handler(async () => {
const session = await useAppSession();

if (!session.data.name) {
return null;
}
return { name: session.data.name };
});

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "Start Example",
      },
    ],
    links: [
      {
        rel: "stylesheet",
        href: appCss,
      },
    ],
  }),
  component: RootComponent,
  beforeLoad: async () => {
    const user = await fetchUser();

    return { user };

},
});

function RootComponent() {
return (

<RootDocument>
  <Outlet />
</RootDocument>
); }

function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
return (

<html>
  <head>
    <HeadContent />
  </head>
  <body className="bg-white dark:bg-slate-900">
    <div className="min-h-screen flex flex-col">{children}</div>
    <Scripts />
  </body>
</html>
); }

export const Route = createFileRoute("/_app")({
  component: RouteComponent,
  beforeLoad: async ({ context }) => {
    const isLoggedIn = !!context.user;

    if (!isLoggedIn) {
      throw redirect({
        to: "/",
      });
    }
  },
});

function RouteComponent() {
  const logout = useServerFn(logoutAction);

  return (
    <div className="flex flex-col flex-1">
      <nav className="flex items-center justify-end py-3 px-4">
        <ul>
          <li
            className="dark:text-white hover:underline cursor-pointer"
            onClick={() => {
              logout();
            }}
          >
            Logout
          </li>
        </ul>
      </nav>
      <div className="px-4">
        <Outlet />
      </div>
    </div>
  );
}

Et voilà, maintenant toutes les routes enfant de notre layout _app sont protégées !

Routes API

Comme tout framework full-stack qui se respecte, Start dispose d'un concept de routes API. La notation de fichier pour le routing est la même que pour nos pages classiques.

Créons une route API nous permettant de récupérer notre liste de posts :

export const APIRoute = createServerFileRoute("/api/posts").methods({
  GET: async ({ request }) => {
    return json(posts);
  },
});

Que ce soit pour les server functions ou les routes API, il est possible d'utiliser tout un ensemble de fonctions utilitaires fournies par Stack afin de gérer à le contenu d'une requête et d'une réponse. C'est le cas de la fonction json. Par exemple si l'on souhaite renvoyer un statut HTTP particulier pour notre requête :

export const APIRoute = createServerFileRoute("/api/posts").methods({
  GET: async ({ request }) => {
    setResponseStatus(200);
    return json(posts);
  },
});

Middlewares

Les middlewares sont des fonctions que l'on branche aux server functions afin d'intercepter l'exécution de celles-ci. Elles permettent d'ajouter du contexte à nos requêtes, que ce soit lors de l'exécution côté client ou côté serveur.

Créons un middleware afin de rediriger l'utilisateur vers la page d'accueil s'il tente d'accéder à notre liste de posts en tant qu'utilisateur anonyme.

export const authMiddleware = createMiddleware().server(async ({ next }) => {
  const user = await useAppSession();

if (!user.data.name) {
throw redirect({
to: "/",
});
}

return next();
});

export const loadPosts = createServerFn()
  .middleware([authMiddleware])
  .handler((async) => {
    return posts;
  });

Et voilà, maintenant le handler de notre server function ne s'exécutera uniquement si l'utilisateur est authentifié.

Un middleware est aussi utilisable sur une route API :

export const APIRoute = createServerFileRoute("/api/posts").methods((api) => ({
  GET: api.middleware([authMiddleware]).handler(async ({ request }) => {
    setResponseStatus(200);
    return json(posts);
  }),
}));

DevTools

Un gros quick win par rapport à Next : la possibilité de débugger les routes (les données du loader par exemple). Cela est disponible via les DevTools de TanStack Router, à intégrer directement au sein du composant RootDocument.

Déploiement

Le déploiement d'une application Start est très simple. Différents presets sont fournis, à passer soit au sein de la configuration, soit via un flag au moment du build. Pour un simple serveur node par exemple :

yarn build
node .output/server/index.mjs

Start supporte les services d'hébergements les plus importants du marché comme Vercel et Netlify.

Conclusion

Globalement j'ai eu une bonne expérience avec Start. Une DX très agréable, une documentation très complète (comme toutes les librairies TanStack) et toutes les fonctionnalités que l'on attends d'un framework full-stack. Le fonctionnement des server functions est, selon moi, bien mieux que sur NextJS (méthode GET/POST, réponse customisable). L'ajout de devtools liés au routing est aussi un énorme plus. C'est en tout cas une solution sur laquelle nous allons garder un oeil attentif, car c'est une alternative très intéressante par rapport à NextJS. Une idée de projet qui nécessiterait TanStack Start ? Utilisez notre estimateur de projet !