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.

import { createAccessControl } from 'better-auth/plugins/access'

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 :

import { statement } from '@/lib/auth/permissions'

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'

import { auth } from '@/lib/auth'
import { ERROR_MESSAGES } from '@/utils/constants'
import { Entities, PermissionFor } from '@/utils/organization/permissions'
import { headers } from 'next/headers'

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 :

import { betterAuth } from 'better-auth'
import { organization } from 'better-auth/plugins'

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.

import { betterAuth } from 'better-auth'
import { organization } from 'better-auth/plugins'

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 :

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { z } from 'zod'
import { readFileSync } from 'node:fs'

// 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.

import React, { useEffect, useState } from 'react'
import { createRoot } from 'react-dom/client'

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.

import { FastMCP } from '@modelcontextprotocol/sdk/server/fastmcp.js'

// 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
import { z } from 'zod'

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

import { describe, it, expect } from 'vitest'
import { server } from './server.js'

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

import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

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

import { createAuthClient } from "better-auth/react";

const authClient = createAuthClient();

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

import { auth } from "@/auth";
import { toNextJsHandler } from "better-auth/next-js";

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.

import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"

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

import { createAuthClient } from "better-auth/client"
import { organizationClient } from "better-auth/client/plugins"

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/> :

import { useRive, useStateMachineInput } from '@rive-app/react-canvas'

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 :

import { StyleSheet } from 'react-native-unistyles';
import { View } from 'react-native';

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 :

import { StyleSheet } from "react-native-unistyles";

// 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 :

import { registerRootComponent } from "expo";
import "./src/theme";
import App from "./src/app";

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).

import { StyleSheet } from 'react-native-unistyles';
import { View } from 'react-native';

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 :

import { StyleSheet } from 'react-native-unistyles';
import { View } from 'react-native';

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 :

import { StyleSheet } from 'react-native-unistyles';
import { View } from 'react-native';

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é.

import { PropsWithChildren } from "react";
import {
  Pressable,
  type PressableProps,
  StyleProp,
  Text,
  ViewStyle,
} from "react-native";
import Animated, {
  useAnimatedStyle,
  withTiming,
} from "react-native-reanimated";
import { StyleSheet, type UnistylesVariants } from "react-native-unistyles";
import { useAnimatedVariantColor } from "react-native-unistyles/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.

import { StyleSheet } from 'react-native-unistyles';
import { View } from 'react-native';
import Button from './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é.

import { StyleSheet, UnistylesRuntime } from 'react-native-unistyles';
import { View } from 'react-native';
import Button from './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="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.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import pg from "pg";

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";
import { useChat } from "ai/react";
import Markdown from "react-markdown";

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.

import { anthropic } from "@ai-sdk/anthropic";
import { experimental_createMCPClient, streamText } from "ai";
import { Experimental_StdioMCPTransport } from "ai/mcp-stdio";
import { NextRequest } from "next/server";

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,
  },
}

import { defineConfig } from 'vite'
import tailwindcss from "@tailwindcss/vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";

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.

import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

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.

import type { ReactNode } from "react";
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
// import de la feuille de style au format URL
import appCss from "../styles/styles.css?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.

import { createFileRoute, redirect } from "@tanstack/react-router";

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.

import { createFileRoute } from "@tanstack/react-router";
import PostCard from "../components/PostCard";
import { loadPosts } from "../functions/posts";

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>
); }

import { Link } from "@tanstack/react-router";

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 :

import { createServerFn } from "@tanstack/react-start";
import { posts } from "../mocks/posts";

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.

import { createServerFn, json } from '@tanstack/react-start'
import { setResponseStatus } from '@tanstack/react-start/server'
import { z } from 'zod'
import { redirect } from '@tanstack/react-router'
import { setTimeout } from 'node:timers/promises'
import { useAppSession } from '../utils/session'

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: '/',
  })
})

import { json } from '@tanstack/react-start'
import { useSession } from '@tanstack/react-start/server'

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: {},
  })
}

import { createFileRoute } from '@tanstack/react-router'
import { useServerFn } from '@tanstack/react-start'
import { loginAction } from '../functions/auth'

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 :

import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { useServerFn } from "@tanstack/react-start";
import { logoutAction } from "../functions/auth";

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.

import type { ReactNode } from "react";
import {
  Outlet,
  createRootRoute,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import appCss from "../styles/styles.css?url";
import { useAppSession } from "../utils/session";

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>
); }

import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { useServerFn } from "@tanstack/react-start";
import { logoutAction } from "../functions/auth";

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 :

import { json } from "@tanstack/react-start";
import { createServerFileRoute } from "@tanstack/react-start/server"
import { posts } from "../../../mocks/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 :

import { json } from "@tanstack/react-start";
import { setResponseStatus, createServerFileRoute } from "@tanstack/react-start/server";
import { posts } from "../../../mocks/posts";

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.

import { createMiddleware } from "@tanstack/react-start";
import { redirect } from "@tanstack/react-router";
import { useAppSession } from "../utils/session";

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

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

return next();
});

import { createServerFn } from "@tanstack/react-start";
import { authMiddleware } from "../middlewares/auth";
import { posts } from "../mocks/posts";

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 :

import { json } from "@tanstack/react-start";
import { setResponseStatus, createServerFileRoute } from "@tanstack/react-start/server";
import { posts } from "../../../mocks/posts";
import { authMiddleware } from "../../../middlewares/auth";

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 !

Introduction

Avec la démocratisation de ces outils, beaucoup de personnes ont pu expérimenter et utiliser les modèles de langage "génériques", je précise génériques car ces LLMs sont entraînés sur des données générales et ne sont donc pas spécialisés dans un domaine précis. Ce qui peut rapidement devenir un frein lorsque l'on souhaite générer des réponses précises et contextuelles. Les structures souhaitant exploiter les LLMs pour leurs besoins ont donc dû trouver des solutions pour améliorer la qualité des réponses générées. Deux solutions sont apparues :

• Fine-Tuning sur un modèle générique
• RAG (Retrieval-Augmented Generation)

Dans cet article, nous allons nous aborder les inconvénients de la première solution, le Fine-Tuning, et nous concentrerons sur la seconde solution, le RAG, et comment il peut être utilisé pour améliorer la qualité des réponses générées par les LLMs et comment le mettre en place. Nous allons expliquer de manière détaillée comment fonctionne un RAG et comment le mettre en place de manière générale, il existe cependant de nombreuses variantes de ce système qui vont dépendre des modèles de langage et/ou des plateformes utilisées. L'idée est donc de comprendre les principes généraux et de pouvoir les appliquer à des cas concrets.

TL;DR

Pour résumer, un RAG combine la puissance des LLMs avec des connaissances spécifiques issues de vos documents. Ce système transforme d'abord vos données en représentations vectorielles (embeddings) stockées dans une base dédiée. Lorsqu'une question est posée, le système recherche automatiquement les informations les plus pertinentes dans cette base par recherche vectorielle ou similarity search et les ajoute comme contexte à la requête envoyée au LLM, permettant ainsi des réponses précises et basées sur vos données privées. Il permet également d'éviter les hallucinations qui peuvent survenir lors de l'utilisation de LLMs sur des sujets précis pour lesquels il n'a pas été entraîné.

Fine-Tuning

Les LLMs sont des modèles de langage qui sont entraînés sur des données générales, ce qui leur permet de générer des réponses très performantes. Cependant, il est possible de les entraîner sur des données spécifiques à un domaine, ce qui leur permet de générer des réponses plus précises et contextuelles, on peut voir cela comme un sur-entraînement du modèle sur les données spécifiques. Cela peut être une solution efficace mais qui comporte des inconvénients :

• L'entraînement peut être coûteux en temps et en ressources
• L'entraînement se fait sur des données statiques, il est donc nécessaire de mettre à jour le modèle régulièrement pour maintenir les connaissances à jour
• Il est nécessaire de gérer les données d'entraînement, ce qui peut être une tâche complexe et fastidieuse

Évidemment, cette solution n'est pas sans intérêt, elle permet dans certains usages de générer des réponses très performantes. Mais ici nous allons nous intéresser à un usage plutôt orienté Question/Réponse qui sera censé répondre de manière précise et contextuelle à une question. Pour cela, nous allons nous tourner et approfondir une autre solution: le RAG.

Retrieval-Augmented Generation

Un RAG pour Retrieval-Augmented Generation est un système qui va nous permettre d'enrichir nos questions envoyées à un LLM avec des informations contextuelles. Pour ce faire, il utilise l'embedding (ou plongement vectoriel) des documents et une base de données vectorielle pour stocker ces vecteurs. Cela nécessite de mettre en place et de remplir, en amont, la base de données vectorielle avec nos documents. Enfin, lors de l'envoi d'une question au LLM, celui-ci recevra non seulement la question originale mais également le contexte des documents les plus proches de la question grâce à la recherche vectorielle ou similarity search.

Comment fonctionne un RAG ?

Comme nous l'avons vu précédemment, une étape importante d'un RAG est de mettre en place et de remplir la base de données vectorielle avec nos données. Cette étape est primordiale pour le bon fonctionnement du RAG. Nous allons revenir en détails sur les différentes manières de créer ces embeddings.

Une fois que ces embeddings sont créés, lors de l'envoi d'une question au LLM, celle-ci sera vectorisée et comparée aux vecteurs des documents présents dans la base de données vectorielle. Cette comparaison permettra de récupérer les quelques morceaux de documents les plus pertinents et de les envoyer au LLM en plus de la question originale.

Il suffira alors au LLM de générer une réponse en s'appuyant sur le contexte fourni en entrée.

Travail préliminaire

Les données d'entrée

Une partie importante d'un RAG est la qualité des données utilisées pour créer les embeddings. En effet, plus les données sont pertinentes et contextuelles, plus la réponse générée par le LLM sera précise.

L'origine et le format des données d'entrée sont très variés. En effet, il peut s'agir de documents textuels, d'images, de pdf, de tableurs, et même de données extraites directement d'une base de données. Il est donc important de pouvoir les traiter de manière uniforme et de pouvoir les convertir en embeddings. La seule contrainte est que les données doivent être convertibles en texte.

Dans certains cas, il peut être nécessaire de convertir les données en texte. Par exemple, si les données sont des images, il est possible de les convertir en texte en utilisant des modèles de vision par ordinateur, ce qui permettra d'obtenir une description textuelle du contenu de l'image. Pour les PDFs, il est possible d'utiliser des modèles d'OCR (Optical Character Recognition) pour extraire le texte comme Mistral OCR par exemple.

Partitionnement ou chunking

Le partitionnement ou "chunking" est l'étape qui consiste à découper nos documents en morceaux plus petits afin de les stocker dans notre base de données vectorielle. Cette étape est cruciale car elle influence directement la performance de notre RAG.

Taille des chunks

La taille des chunks est un paramètre important à considérer lors de la mise en place d'un RAG. Il faut souvent expérimenter avec différentes tailles et différents niveaux de chevauchement pour trouver la configuration optimale. Les chunks plus petits permettent généralement une recherche plus précise, car ils contiennent moins de texte de remplissage qui pourrait diluer la représentation sémantique. Cela aide le système RAG à identifier et extraire plus efficacement les informations pertinentes. Toutefois, cette précision s'accompagne d'un coût : les chunks plus petits augmentent le temps de traitement et les ressources nécessaires.

Méthodes de découpage

Bien que la méthode la plus simple soit de découper le texte par caractère, d'autres options existent selon le cas d'utilisation et la structure du document :

• Par tokens : pour éviter de dépasser les limites de tokens dans les appels API
• Par phrases ou paragraphes : pour maintenir la cohérence des chunks
• Par en-têtes HTML ou propriétés JSON : pour respecter la structure du document
• Par morceaux de code significatifs : si vous travaillez avec du code, il est souvent recommandé d'utiliser un analyseur d'arbre syntaxique abstrait (AST)

Embeddings

Maintenant que nous avons nos données partitionnées, nous pouvons les convertir en embeddings, c'est-à-dire en vecteurs qui vont représenter nos données et nous permettre de capturer leur signification sémantique. Pour ce faire, nous allons utiliser un modèle d'embedding comme mistral-embed de Mistral ou text-embedding-3-small de OpenAI par exemple.

Base de données vectorielle

La base de données vectorielle est un outil essentiel pour stocker et récupérer les embeddings. Elle va nous permettre de stocker les vecteurs et de les récupérer rapidement. Il existe plusieurs solutions pour mettre en place une base de données vectorielle, soit dédiées au RAG, soit intégrées à une pile logicielle existante si celle-ci le permet. Parmi les solutions les plus courantes, on peut citer Pinecone, Faiss, Annoy, HNSW ou encore Milvus.

Si votre projet utilise déjà une base de données PostgreSQL, il est possible d'utiliser l'extension pgvector pour stocker et récupérer les embeddings. Cela permet de bénéficier d'une base de données vectorielle nativement intégrée à votre projet et donc de créer des liens entre vos données et vos embeddings. Très utile lorsque l'on souhaite récupérer des informations relatives à des documents.

Voilà, nous avons maintenant nos données partitionnées, nos embeddings et notre base de données vectorielle. Nous pouvons maintenant passer à la phase d'interprétation des questions et de génération de réponses en créant un Assistant RAG.

Création d'un Assistant RAG

Cette manière d'utiliser un RAG va fortement dépendre de la plateforme utilisée et/ou du framework utilisé, dans certains cas, il sera possible de créer un Assistant RAG découplé de votre application, comme sur la plateforme OpenAI. Autrement, il sera nécessaire de créer un Assistant RAG couplé à votre application en définissant les outils et la manière de les utiliser explicitement directement dans le code de votre application.

Définir les outils

Par outil, nous entendons les différentes fonctions qui vont être utilisées pour récupérer les données dans la base de données vectorielle et les utiliser pour générer des réponses précises et contextuelles.

Recherche vectorielle

La recherche vectorielle est la fonction qui va permettre de récupérer les données dans la base de données vectorielle en fonction de la question.

Dans un premier temps, il faudra transformer la question en vecteur grâce au modèle d'embedding que nous avons utilisé pour créer nos embeddings plus tôt. De cette manière, nous pourrons comparer le vecteur de la question à tous les vecteurs des documents présents dans la base de données vectorielle à l'aide d'une fonction de recherche vectorielle comme similarity avec l'extension pgvector de PostgreSQL.

Cette recherche vectorielle va nous permettre d'obtenir les documents les plus proches de la question, c'est-à-dire les documents qui ont le plus de ressemblance avec la question.

Pour l'exemple, nous allons utiliser la fonction similarity avec l'extension pgvector de PostgreSQL.

export const findRelevantContent = async (userQuery: string) => {
  const embedding = await generateEmbedding(userQuery);
  const vectorQuery = `[${embedding.join(",")}]`;
  const embeddings = await db.$queryRaw
  `
      SELECT
        embeddings.id,
        embeddings.content,
        documents.name,
        1 - (embedding <=> ${vectorQuery}::vector) as similarity
      FROM embeddings
      INNER JOIN documents ON embeddings.document_id = documents.id
      WHERE 1 - (embedding <=> ${vectorQuery}::vector) > .5
      ORDER BY similarity DESC
      LIMIT 5;
    `;
  return embeddings;
};

Ici on limite la recherche à 5 chunks ayant une similarité supérieure à 0.5. Cette valeur est arbitraire et peut être ajustée en fonction de la pertinence des résultats.

Prompt

Le prompt est le texte qui va être envoyé au LLM pour générer une réponse. Il va contenir les directives pour le LLM afin qu'il génère une réponse pertinente en lui précisant d'utiliser l'outil de recherche vectorielle pour récupérer les documents les plus proches de la question.

C'est dans cette partie qu'il faudra également préciser à l'assistant comment il doit utiliser le contexte des documents.

Pour l'exemple, nous allons utiliser le SDK de Vercel pour générer une réponse en lui précisant d'utiliser l'outil de recherche vectorielle pour récupérer les documents les plus proches de la question.

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await streamText({
    model: model,
    messages: convertToCoreMessages(messages),
    system: `You are a helpful assistant. Check your knowledge base before answering any questions.
    Only respond to questions using information from tool calls.
    If no relevant information is found in the tool calls, respond, "Sorry, I don't know."`,
    tools: {
      getInformation: tool({
        description: `get information from your knowledge base to answer questions.`,
        parameters: z.object({
          question: z.string().describe("the users question"),
        }),
        execute: async ({ question }) => findRelevantContent(question),
      }),
    },
    toolChoice: "required",
  });
  return result.toAIStreamResponse();
}

Conclusion

Vous l'aurez compris, le RAG est un outil puissant qui peut être utilisé pour générer des réponses précises et contextuelles et éviter tout problème d'hallucinations, fréquent lors de l'utilisation de LLMs sur des sujets complexes. En orientant et en contextualisant les questions envoyées au LLM, il est possible d'obtenir des réponses qui s'appuient réellement sur vos données.

Les cas d'utilisation sont nombreux, chez Premier Octet, nous avons déjà pu mettre en place des RAGs sur des projets de chatbots et de génération de réponses, pour des structures qui souhaitaient utiliser la puissance des LLMs tout en l'adaptant à leurs propres besoins et leurs données.

Si vous avez des retours d'expérience sur ces sujets-là, ou que vous souhaitez en savoir plus sur le RAG, n'hésitez pas à nous contacter.

Références

• Mistral OCR - Optical Character Recognition Model
• OpenAI - Embedding Model
• Pinecone - Vector Database
• pgvector - Vector Extension for PostgreSQL
• Vercel AI SDK - AI SDK
• LangChain - AI SDK

J’espère que ce récit motivera celles et ceux qui commencent tout juste leur parcours. Et pour les développeurs plus expérimentés, peut-être vous rappellera-t-il avec une pointe de nostalgie vos premières années de junior.

Picksale : une toile vierge

Une plateforme e-commerce qui permet aux créateurs d’ouvrir leur boutique en ligne. Voilà les grandes lignes du projet que l’on m’avait confié il y a 2 ans. Je me rappelle avoir hoché la tête avec l’assurance d’une experte, mais une fois face à ma toile virtuelle, j’avais vite pris conscience de l’ampleur de la tâche.

Si un artiste peut être paralysé par une toile blanche, un développeur junior l’est tout autant devant un repo fraîchement cloné. Heureusement, je n’étais pas seule dans cet atelier numérique. Mon tuteur et mes collègues étaient là pour m’aider à mélanger mes premières couleurs. Ils n’ont pas seulement répondu à mes questions, ils m’ont également appris à chercher les réponses par moi-même.

Et dans cette quête, voici la palette d’outils qui m’avait été confiée pour donner vie à Picksale :

🎨 React & Next.js – Mon pinceau et ma palette. Next.js m’a enseigné l’art du rendu client et serveur, des concepts qui, à l’époque, me semblaient aussi mystérieux qu’un tableau abstrait.

🖍 Chakra UI – Un set de couleurs prêt à l’emploi. Plutôt que de réinventer la roue en CSS, j’ai appris à styliser les composants avec une simplicité déconcertante. Un peu comme peindre avec des numéros : utilisez les bons composants, et tout prend forme.

🛠 Prisma – Mon guide pour dompter la base de données. Manipuler PostgreSQL directement ? Trop brutal pour mes débuts. Prisma a été mon pinceau fin, me permettant d’écrire et de lire les données avec simplicité et précision.

💳 Stripe – Le vernis final. Gérer des paiements en ligne ? Un défi de taille. Mais avec Stripe, j’ai compris que la complexité pouvait être encapsulée derrière des API bien pensées. J’ai encore ce frisson du premier paiement réussi sur Picksale, un peu comme voir son tableau encadré dans une galerie.

Une œuvre d’art… vraiment ?

S’engager sans planifier, c’est planifier son échec. Moi, j’ai non seulement planifié, mais j’ai aussi consacré des heures à concevoir… une véritable monstruosité. Quand je repense à ma première maquette, je ne peux m’empêcher de rire (et de rougir). Dans mon esprit, le rendu était élégant, innovateur, minimaliste… dans la réalité, c’était un cauchemar pastel sur fond de naïveté.

Si je devais vous décrire cette œuvre d’art, ce serait une agression visuelle : une palette de couleurs à faire pleurer un arc-en-ciel, des boutons aussi massifs qu’un donut, et un design qui ferait pâlir un site web des années 90. Heureusement, l’un de mes collègues a fini par intervenir et a sauvé la direction artistique de Picksale en lui offrant un coup de pinceau moderne et épuré. Malgré cette refonte salvatrice, mon chef-d’œuvre original reste figé dans les commits de GitHub et les déploiements de Vercel.

J’espère juste que personne ne sera assez curieux pour la déterrer… ou qu’il fera preuve d’un peu d’indulgence dans ses critiques.

Apprendre à peindre à plusieurs

Après des mois de travail acharné, Picksale était devenu mon bébé. Mon code, mes décisions, mon précieux. Si quelqu’un proposait une modification, j'avais tendance à me montrer aussi protectrice qu’un chat qui garde sa pâtée.

Avec le temps, heureusement, j'ai appris à lâcher prise et à ouvrir mon esprit. Travailler avec ma collègue m'a aidée à comprendre que le travail d'équipe n'était pas une contrainte, mais un atout. Au début, ses choix de couleurs et de formes étaient différents de ce que j'aurais imaginé. Mais petit à petit, j'ai compris que j’avais également accès à sa palette unique : son expertise, sa vision, et sa manière de voir les choses autrement.

La collaboration, ce n'est pas juste un compromis, mais plutôt une fusion d'idées qui donne quelque chose de bien plus fort et riche que ce que j'aurais pu créer seule. Un projet, c’est comme un grand tableau où chaque touche compte, même celles qui ne viennent pas de notre pinceau.

L’Art du Débugging

Si au début tout ressemblait à une belle toile blanche, une fois Picksale arrivé à maturité, le tableau s’est compliqué. Bugs imprévisibles, pertes de données mystérieuses, comportements étranges surgissant uniquement en production (bien évidemment).

Chaque jour amenait son lot de surprises, rarement agréables. J’ai connu le stress de voir une fonctionnalité casser sans raison apparente et l’angoisse de corriger un bug qui en générait trois nouveaux. Face à ma détresse, un collègue (apôtre des tests automatisés) m’a tendu la main : l'heure était venue de faire entrer Playwright dans nos vies. Depuis, à chaque pull request, cet outil se dresse tel un critique d'art intransigeant — parfois bienveillant, souvent cruel, mais toujours juste.

Aujourd'hui, à force de plonger dans ces problèmes, j’ai appris à garder mon sang-froid et à affiner ma méthode. Même si l’idée de tomber sur un bug compliqué me donne toujours des sueurs froides, je sais que j’ai les outils et l’expérience nécessaires pour le régler. Après tout, le développement, c’est un peu comme la restauration d’un tableau ancien : il y aura toujours des fissures à réparer, mais avec de la patience et les bons outils, rien n’est irrécupérable.

Et aujourd’hui ?

Ce projet qui m’a tant appris est désormais une plateforme robuste qui a pour but de pour simplifier la vie des artistes, designers et petits artisans du web.

Avec Picksale, chacun peut modeler sa boutique à son image :

🎨 Personnalisation avancée – Choisissez vos couleurs, votre typographie et ajoutez des bannières pour créer un espace qui vous ressemble.

📄 Pages CMS et Portfolio – Racontez votre histoire, partagez votre univers et exposez vos créations comme dans une vraie galerie.

🚚 Système de livraison flexible – Après un long travail de réflexion et plusieurs refonte, Picksale propose désormais un système de profils de livraison pensé dans les moindres détails, conçu pour gérer les ventes locales et internationales.

📦 Gestionnaire de commandes – De la confirmation à l’envoi, suivez vos ventes et tenez vos clients informés grâce aux e-mails automatique.

🛠 Et bien plus encore – Picksale continue d’évoluer avec toujours plus d’outils pour accompagner ses utilisateurs !

Aujourd’hui, la plateforme compte plus de 100 boutiques et près de 600 commandes passées. Pour ceux qui veulent aller encore plus loin, le plan Pro propose un tableau de bord analytique alimenté par Plausible pour suivre ses performances, des codes de réduction, des e-mails personnalisés et une tonne de nouveautés à venir !

Si vous cherchez un moyen rapide et efficace de lancer votre boutique en ligne, je ne peux que vous inviter à y jeter un coup d'œil. Et qui sait ? Peut-être que votre propre aventure débutera sur cette même toile blanche qui a tant compté pour moi.

Conclusion

Comme vous l’aurez compris, tout ne s’est pas fait en un coup de pinceau. J’ai écrit tellement de lignes de code avec fierté... avant de les effacer dans la panique quelques jours plus tard. Entre mes useEffect qui tournaient en boucle et mes composants qui se rafraîchissaient de manière épileptique, j’avais parfois l’impression que mon application prenait vie… dans le mauvais sens du terme.

Mais chaque bug était une retouche, chaque refactorisation un coup de pinceau plus précis. Peu à peu, j’ai appris à voir le code autrement : non plus comme une simple liste d’instructions, mais comme une œuvre évolutive qui se perfectionne ligne après ligne.

Deux ans plus tard, Picksale est devenu un projet solide avec une équipe agrandie, et moi, je suis devenue une développeuse bien plus confiante. Je ne saurais vous décrire la joie de recevoir les premiers retours positifs de nos utilisateurs, ce compteur grimpe petit à petit avec le temps et c’est une grande source de fierté que de voir des personnes utiliser un outil que l’on a imaginé.

Si vous êtes junior et que vous doutez, sachez ceci : au début, on a tous l’impression de peindre avec des moufles. Mais avec du temps, des erreurs et des bons conseils, on finit par maîtriser ses coups de pinceau.

Alors accrochez-vous, demandez de l’aide, et surtout, continuez à peindre. Un jour, vous regarderez votre premier projet avec la même fierté que j’ai aujourd’hui en pensant à Picksale.

Bon code et belles toiles ! 🎨💻

Comparatif technique

En parcourant la documentation officielle, on se rend tout de suite compte que Lynx a puisé beaucoup d'inspiration sur des frameworks déjà existants, notamment React Native et Flutter, afin d'offrir une expérience de développement très proche de celle que l'on pourrait retrouver sur une application Web :

• Bundler moderne basé sur Rspack
• Librairie React basée sur React 17, permettant de faire le pont avec les composants natifs
• Support des feuilles de style CSS et de la majorité des propriétés CSS
• Support des sélecteurs, que ce soit pour du CSS ou au runtime

De la même manière qu'Expo Go, Lynx fournit une application à installer sur son simulateur, Lynx Explorer, permettant d'exécuter un bundle depuis une URL (locale ou distante). C'est d'ailleurs grâce à cela qu'il est possible d'exécuter les différents exemples fournis dans la documentation.

Une application de DevTools est aussi disponible avec un inspecteur d'élément (HTML et natifs) et une console JavaScript. On notera l'absence d'un inspecteur de réseau, fortement appréciable du côté des DevTools Expo.

Côté runtime, on retrouve PrimJS en tant que moteur JavaScript, développé spécifiquement pour Lynx, de la même manière que React Native utilise Hermes.

Niveau support, Lynx a été pensé pour supporter les plateformes mobiles ainsi que le web, de la même manière que React Native supporte Android, iOS (Windows, MacOS, Web supportés aussi par l'intermédiaire de librairies tierces).

La découverte par la pratique

Pour découvrir plus en détail Lynx, nous allons développer une simple application de deux écrans, utilisant l'API JSON Placeholder, pour lister des posts, accéder aux détails d'un post et y lister des commentaires.

Création du projet

Créer un projet Lynx est assez simple :

yarn create rspeedy

Après que le projet soit créé, il ne reste plus qu'à installer les dépendances :

yarn install

Puis on lance notre serveur de développement :

yarn dev

Une URL va être générée. Il suffit de copier-coller cette URL dans l'application Lynx Explorer, et voilà !

Notre premier écran

Entrons dans le vif du sujet en effacant tout le rendu du composant App, et créons notre liste de posts :

import "./App.css";
import PostItem from "./components/PostItem.jsx";
import usePosts from "./hooks/usePosts.js";

export function App() {
  const { data: posts, fetchNextPage } = usePosts();

return (

<list
  className="safe-area posts-list"
  list-type="single"
  lower-threshold-item-count={2}
  bindscrolltolower={() => fetchNextPage()}
>
  {posts?.pages?.flat().map((post) => {
    return (
      <list-item key={post.id} item-key={post.id.toString()}>
        <PostItem body={post.body} id={post.id} title={post.title} />
      </list-item>
    )
  })}
</list>
); }

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

const PostItem = ({ body, id, title }: Props) => {
  return (
    <view className="post-item">
      <text className="post-item-title">{title}</text>
      <text className="post-item-content">{body}</text>
    </view>
  );
};

export default PostItem;

:root {
  background-color: #fefefe;
  --color-text: #000;
}

.safe-area {
  padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(
      safe-area-inset-left
    );
}

.posts-list {
  width: 100%;
  height: 100vh;
  list-main-axis-gap: 16px;
  padding-left: 16px;
  padding-right: 16px;
}

.post-item {
  display: flex;
  flex-direction: column;
  background-color: white;
  border-radius: 12px;
  box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.2);
  padding: 16px;
  gap: 8px;
}

.post-item-title {
  font-size: 16px;
  font-weight: bold;
  color: var(--color-text);
}

.post-item-content {
  font-size: 14px;
  color: var(--color-text);
}

import { useInfiniteQuery } from '@tanstack/react-query'

export type Post = {
  id: number
  title: string
  body: string
  userId: string
}

const usePosts = () => {
  return useInfiniteQuery({
    queryKey: ['posts'],
    queryFn: async ({ pageParam }) => {
      const response = await fetch(
        `https://jsonplaceholder.typicode.com/posts?_page=${pageParam}&_limit=10`
      )
      const data = await response.json()
      return data as Post[]
    },
    getNextPageParam: (lastPage, allPages, lastPageParam) => {
      if (lastPage.length === 0) return undefined
      return lastPageParam + 1
    },
    initialPageParam: 1,
  })
}

export default usePosts

Et voilà, notre liste est prête. On note déjà plusieurs aspects qui diffèrent par rapport à React Native :

• pas d'import de composants (View, Text) : ils sont disponibles via le moteur de rendu (ici la librairie React)
• possibilité d'utiliser des classes CSS. Il est aussi possible de mettre le style directement dans une prop style ou bien d'utiliser l'attribut id, comme en HTML classique

L'élément list a un comportement qui se veut similaire à ce que propose la FlatList de React Native. Cependant, le concept de recyclage des vues est ici totalement natif, là où React Native l'implémente du côté JS, même si plusieurs librairies alternatives tentent de résoudre ce problème (FlashList, Legend List, ShadowList). L'API fournie pour la liste de Lynx est assez complète, rendant ainsi le système de layout très modulable. Par exemple, pour des listes multi colonnes, il est assez facile de faire qu'un sorte qu'un élément en particulier prenne toute la largeur disponible. La documentation fournit de nombreux exemples présentant différents types de listes assez populaires.

Détail d'un post

Naturellement, nous souhaitons maintenant pouvoir cliquer sur un post pour afficher son détail ainsi que ses commentaires. Nous aurons donc besoin d'un système de navigation...inexistant ! En tout cas, ce système n'est pas fourni par Lynx, qui préconise plutôt d'utiliser React Router en version 6. Alors évidemment ça n'est pas idéal : contrairement à React Navigation qui fournit des composants mappés sur des écrans natifs (donc avec des animations natives), on n'aura aucune animation de navigation, aucun composant natif de navigation (header, tab bar, etc) ou même de possibilité d'interactivité avec les gestures avec React Router. Nous allons tout de même utiliser React Router pour gérer la navigation entre les pages.

import { root } from "@lynx-js/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { MemoryRouter, Route, Routes } from "react-router";
import { App } from "./App.js";
import Post from "./Post.jsx";

const queryClient = new QueryClient();

root.render(

{' '}

<QueryClientProvider client={queryClient}>
  <MemoryRouter>
    <Routes>
      <Route index element={<App />} />
      <Route path="/post/:id" element={<Post />} />
    </Routes>
  </MemoryRouter>
</QueryClientProvider>
, );

if (import.meta.webpackHot) {
import.meta.webpackHot.accept();
}

import { useNavigate } from "react-router";

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

const PostItem = ({ body, id, title }: Props) => {
  const navigate = useNavigate();

  const onTap = () => {
    navigate(`/post/${id}`);
  };

  return (
    <view className="post-item" bindtap={onTap}>
      <text className="post-item-title">{title}</text>
      <text className="post-item-content">{body}</text>
    </view>
  );
};

export default PostItem;

.post-container {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding-left: 16px;
  padding-right: 16px;
}

.post-comment-container {
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.post-comment-container:not(:last-of-type) {
  margin-bottom: 16px;
}

.post-comment-title {
  font-size: 18px;
  font-weight: bold;
  color: var(--color-text);
}

.post-comment-name {
  font-size: 14px;
  font-weight: 600;
  color: var(--color-text);
}

.post-comment-content {
  font-size: 14px;
  color: var(--color-text);
}

import { useQuery } from '@tanstack/react-query'
import type { Post } from './usePosts.js'

type PostWithComments = Post & {
  comments: Comment[]
}

type Comment = {
  id: string
  postId: string
  name: string
  email: string
  body: string
}

const usePost = (id: number) => {
  return useQuery({
    queryKey: ['post', { id }],
    queryFn: async () => {
      const post = await fetch(
        `https://jsonplaceholder.typicode.com/posts/${id}?_embed=comments`
      ).then((response) => response.json())

      return post as PostWithComments
    },
  })
}

export default usePost

Un peu d'animation ?

Composante essentielle des applications mobiles, les animations donnent de la vie à nos écrans. En React Native, bien qu'une API d'animation soit disponible, on a tendance à utiliser la librairie Reanimated qui, dans ses dernières versions, a sorti un support expérimental des animations CSS. Eh bien Lynx supporte cela par défaut, que ce soit via les feuilles de style CSS ou bien de manière impérative via une fonction appelée au runtime.

Ajoutons une animation CSS sur notre liste de posts :

@keyframes bounce {
  0% {
    transform: scale(1);
  }
  50% {
    transform: scale(1.02);
  }
  100% {
    transform: scale(1);
  }
}

.post-item {
  display: flex;
  flex-direction: column;
  background-color: white;
  border-radius: 12px;
  box-shadow: 0px 4px 8px rgba(0, 0, 0, 0.2);
  padding: 16px;
  gap: 8px;
  animation: bounce 2s ease-in-out infinite;
}

Animons maintenant un élément de la liste au moment d'un clic :

import { useNavigate } from 'react-router'

type Props = {
  body: string
  id: number
  title: string
}

const PostItem = ({ body, id, title }: Props) => {
  const navigate = useNavigate()

  const onTap = () => {
    navigate(`/post/${id}`)
  }

  return (
    <view
      className="post-item"
      id={`post-${id}`}
      bindtap={() => {
        lynx.getElementById(`post-${id}`).animate(
          [
            {
              transform: 'rotate(20deg)',
              'animation-timing-function': 'linear',
            },
            {
              transform: 'rotate(0deg)',
              'animation-timing-function': 'linear',
            },
            {
              transform: 'rotate(-20deg)',
              'animation-timing-function': 'linear',
            },
            {
              transform: 'rotate(0deg)',
              'animation-timing-function': 'linear',
            },
          ],
          {
            name: 'shake-rotate-anim',
            duration: 1000,
            iterations: 1,
            easing: 'ease-in-out',
          }
        )
      }}
    >
      <text className="post-item-title">{title}</text>
      <text className="post-item-content">{body}</text>
    </view>
  )
}

export default PostItem

Compatibilité Web

Lynx propose une compatibilité web par défaut, mais sa mise en place est un peu plus complexe que ce que propose Expo par exemple.

Tout d'abord il faut modifier notre fichier lynx.config.ts à la racine :

import { defineConfig } from '@lynx-js/rspeedy'

import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin'
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin'

export default defineConfig({
  plugins: [
    pluginQRCode({
      schema(url) {
        // We use `?fullscreen=true` to open the page in LynxExplorer in full screen mode
        return `${url}?fullscreen=true`
      },
    }),
    pluginReactLynx(),
  ],
  environments: {
    web: {
      output: {
        assetPrefix: '/',
      },
    },
    lynx: {},
  },
})

Puis on crée un bundle :

yarn build

On crée ensuite un projet rsbuild à la racine de notre projet Lynx :

yarn create rsbuild

Dans notre nouveau projet, on install de nouvelles dépendances :

yarn add @lynx-js/web-core @lynx-js/web-elements

On édite ensuite le fichier src/App.tsx :

import '@lynx-js/web-core/index.css'
import '@lynx-js/web-elements/index.css'
import '@lynx-js/web-core'
import '@lynx-js/web-elements/all'

const App = () => {
  return <lynx-view style={{ height: '100vh', width: '100vw' }} url="/main.web.bundle"></lynx-view>
}

export default App

On édite ensuite le fichier rsbuild.config.ts :

import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import path from 'node:path'
import { fileURLToPath } from 'node:url'
const __filename = fileURLToPath(import.meta.url)
const __dirname = path.dirname(__filename)

export default defineConfig({
  plugins: [pluginReact()],
  server: {
    publicDir: [
      {
        name: path.join(__dirname, '..', 'dist'),
      },
    ],
  },
})

Puis on lance notre serveur de développement :

yarn dev

L'app est disponible sur http://localhost:3000. En inspectant le HTML rendu, on remarque une structure peu conventionnelle, remplie de web components, et très peu de tags natifs. Notre animation au clic implémentée précédemment ne fonctionne pas non plus. On a ce sentiment que le support web n'est pas vraiment au point, mais il est présent !

Performances

Côté performances, Lynx est assez similaire à ce que propose React Native, mais propose une fonctionnalité supplémentaire : l'Instant First-Frame Rendering, qui est très semblable au concept de SSR que l'on connaît dans l'univers de React. L'IFR permet d'afficher le premier écran de notre application de manière quasi instantanée.

Architecturalement parlant, Lynx utilise, tout comme React Native, deux threads. Il est possible de choisir sur quel thread exécuter nos fonctions grâce aux directives 'background only' et 'main thread' en fonction du contexte d'utilisation. Par exemple pour une requête asynchrone comme l'envoi d'un formulaire, on privilégiera la directive 'background only' afin de ne pas bloquer le thread principal. Pour une fonction qui demande un résultat le plus rapidement possible, on privilégiera la directive 'main thread'. Ce concept n'est pas sans rappeler les worklets de Reanimated, permettant l'exécution de fonctions dans le thread UI ou d'autres threads.

Conclusion

Bien que prometteur sur bien des aspects, Lynx est à l'heure actuelle encore trop jeune pour être réellement utilisé de la même manière que l'on pourrait utiliser React Native. On a ce sentiment que la librairie a été dévelopée pour être intégrée à une app existante, et non pour créer une application complète. Beaucoup d'API assez essentielles sont manquantes par rapport à ce que l'on peut trouver en React Native. J'ai personnellement été surpris de voir que Lynx ne supporte l'élément input que par l'application Lynx Explorer, sans qui on ne pourrait tout simplement pas avoir de champ de saisie.

Tous ces éléments ont déjà été remontés par la communauté et seront déployés petit à petit dans les prochaines releases de 2025. Pour le moment, il est encore trop tôt pour se lancer dans la conception d'une application, mais nous allons tout de même garder un oeil sur l'évolution de la librairie.

Bien que cette approche soit encore en phase de test et peu documentée, elle ouvre la voie à une simplification des animations que l’on considérait jusqu’ici comme complexes.

Avant d’aborder son utilisation dans Next.js, je vais rapidement vous présenter l’API dans sa version native pour celles et ceux qui ne seraient pas encore familiers avec elle. Si vous êtes déjà familier avec l’API, vous pouvez directement passer à cette section.

Qu'est-ce que l'API View Transition ?

L'API View Transition est une fonctionnalité native du navigateur qui permet d’animer les changements d’états du DOM (ou de navigation) sans avoir recours à une librairie tierce comme Framer Motion ou GSAP. Elle simplifie grandement l’intégration de transitions / animations visuelles lors de la mise à jour du contenu d’une page.

startViewTransition

Le cœur de cette API repose sur la méthode startViewTransition.

document.startViewTransition(() => updateTheDOMSomehow())

Appeler cette méthode, en lui passant en callback une fonction qui met à jour le DOM, déclenche un cycle de view transition.

Qu'est-ce que ça veut dire ? Essentiellement, à l'appel de cette méthode, l'API capture l'état de la page. Une fois l'opération terminée (la capture de la page) c'est votre fonction de mise à jour du DOM qui est appelée et l'API capture ensuite de nouveau l'état de la page, après votre mutation du DOM.

L’API construit ensuite une arborescence qui ressemble à celle-ci :

::view-transition 
└─ ::view-transition-group(root)
   └─ ::view-transition-image-pair(root)
      ├─ ::view-transition-old(root)
      └─ ::view-transition-new(root)

Comme son nom l’indique ::view-transition-old représente la capture de l’ancienne vue et, vous l’aurez compris, ::view-transition-new la capture actuelle de la vue.

L’ancienne vue est animée en fade out tandis que la nouvelle apparaît en fade in (via la propriété CSS opacity). C’est le comportement par défaut, mais il peut bien sûr être customisé (c'est là tout l'intérêt).

Customiser ses transitions

Pour customiser les view transitions on utilisera les pseudo selecteurs ::view-transition.... en CSS.

Ainsi, si je souhaite faire une transition un peu plus complexe (qu'un fade in / out) je peux cibler ma transition de vue et y appliquer une animation CSS de mon choix.

Par exemple, ici, j’applique respectivement mes animations pop-in et pop-out que j’aurai définies plus haut dans ma feuille de style.

::view-transition-old(root) {
  animation: pop-out 0.3s ease;
}

::view-transition-new(root) {
  animation: pop-in 0.3s ease;
}

Cibler un élément précis

Dans l’exemple précédent, nous avons utilisé un view transition sur l’ensemble de la page (root) mais il est possible de cibler un élément précis.

Pour ce faire, on doit d’abord lui donner un nom de vue de transition (view-transition-name).

.box {
  view-transition-name: box;
}

On pourra ensuite cibler la vue de transition liée à cet élément avec les pseudo éléments correspondants:

::view-transition-old(box) {
	animation: skew-out 0.3s ease;
}

::view-transition-new(box) {
  animation: skew-in 0.3s ease;
}

Deux types de transitions

Les transitions de vues se découpent en deux catégories.

Les transitions de vues sur le même document et celles sur multi-documents (transition de changement de page). Les deux catégories reposent sur les mêmes principes à la différence que pour une transition multi-documents on n’a pas besoin d’appeler la méthode startViewTransition pour démarrer la transition. C’est la navigation entre les documents qui déclenchera la transition.

Nous voilà globalement à jour sur l’état de l’API View Transition (au jour de la rédaction de cet article).

Si vous souhaitez approfondir plus en détails l’API je vous recommande la documentation MDN (quoiqu'un peu légère), la spécification W3C et les nombreux articles de Chrome For Developpers sur le sujet.

Activer la magie des transitions dans Next.js

Récemment, une fonctionnalité a été introduite pour faciliter l’intégration de l'API View Transition dans les projets Next.js. Mais attention, on entre ici dans un territoire très peu documenté.

Cette fonctionnalité, apparue lors d'une release il y a quelques mois, est encore marquée comme experimental. À l’heure où j’écris ces lignes, la documentation officielle est assez minimale sur le sujet (voici le lien si vous voulez jeter un œil) et les ressources restent rares.

C’est justement ce manque de documentation qui m’a poussé à creuser un peu.

En fouillant un peu, je suis tombé sur une démo partagée par Delba Oliveira, développeuse chez Vercel. Ça m’a donné envie d’approfondir le sujet et d’expérimenter directement avec cette nouvelle API dans un petit projet de test de mon côté. Voici ce que j'en ai retiré.

Spoiler : c’est déjà prometteur.

module.exports = {
  // ...
  experimental: {
    viewTransition: true,
  },
}

Le composant unstable_viewTransition

Actuellement, React expose un composant unstable_viewTransition (oui, le nom annonce la couleur). Il prend plusieurs propriétés :

• name : L'équivalent de view-transition-name en CSS.
• className: Pour assigner une view-transition-class à l'élément.
• exit / enter : Pour ajouter une classe (CSS) à l'animation de sortie ou d'entrée de l'élément. (Au montage ou au démontage du composant)
• Et d'autres propriétés que je n'ai pas encore explorées mais qui sont typées et documentées dans les types de React.

Concrètement, voici à quoi ça peut ressembler dans le code :

import { unstable_viewTransition as ViewTransition } from 'react'

export default function MyComponent() {
  return (
    <ViewTransition name="box">
      <div className="box">Hello</div>
    </ViewTransition>
  )
}

Une démonstration

Et maintenant… une petite demo maison pour montrer ce que ça donne en action dans un mini blog NextJS 👇

Dans cette démo on utilise la transition de vue multi-documents, c’est donc la navigation qui déclenche les transitions. J'ai donné le même name au composant <ViewTransition> utilisé dans la page /blog et la page /blog/post/[slug]. Donc à la navigation entre les deux pages, la transition est appliquée pour animer le changement de page entre ces deux éléments.

Et voici le code source utilisé pour cetté démo.

Limites et perspectives

L’intégration expérimentale de l'API View Transition au sein de Next.js ouvre des perspectives intéressantes pour le développement d’interfaces plus fluides. À l’avenir on pourrait imaginer la configurations de transitions prédéfinies entre les pages à l’instar de NuxtJS.

Néanmoins, comme je l’ai rappelé plusieurs fois tout au long de cet article c’est une fonctionnalité qui n’est encore pas totalement prête pour un usage en production, l’API pourrait changer et sera sûrement encore sujette à évolution.

Bonus : Utilisations créatives de l'API View Transition

En bonus, j'ai rassemblé quelques exemples de sites qui utilisent l'API View Transition de manière créative pour que vous ayez une idée des possibilités qu'elle ouvre.

• https://nmn.sh/
• https://cydstumpel.nl/
• https://x.com/delba_oliveira/status/1897701817431044124
• https://theme-toggle.rdsx.dev/
• https://framer-ground-svelte.vercel.app/layout/page-wipe

Ressources

• MDN View Transition API
• Comment utiliser l'API View Transitions ? Du hello world aux cas complexes.
• NextJS View Transition Demo
• NextJS Documentation View Transition
• Transitions d'affichage pour un même document dans les applications monopages
• Transitions fluides avec l'API View Transition