ChatJS : un monorepo Next.js pour démarrer un chat multi-modèles sans réécrire l'infrastructure

Le problème visé : l'infrastructure de chat que tout le monde réécrit

Le README ouvre sur une phrase qui résume la cible : « Stop rebuilding the same AI chat infrastructure. » Le projet ne vend pas un modèle ni une interface de conversation minimaliste. Il vend l'ensemble des briques qu'on retrouve dans presque tout produit de chat : authentification, sélection parmi plus de 120 modèles, streaming, appels d'outils. Le public visé est donc une équipe produit qui a déjà décidé de faire du chat son interface principale et qui préfère consacrer son temps à la partie différenciante. Ce n'est pas une bibliothèque à intégrer dans une application existante : c'est une application complète, avec son monorepo, sa base de données et son stockage. Le README le formule ainsi : « Start here and make it your own. » La conséquence pratique est qu'adopter ChatJS revient à accepter une architecture avant d'écrire la première ligne de code métier.

Ce que le CLI génère et ce qu'il vous laisse décider

L'entrée dans le projet est une commande unique : npx @chat-js/cli@latest create my-app. Le paquet @chat-js/cli est publié sur npm et versionné séparément du reste du dépôt, avec des releases récentes en 0.6.5, 0.7.0 et 0.8.0. D'après le README, le CLI « walks you through gateway, features, and auth choices », génère un fichier chat.config.ts, puis affiche la liste des variables d'environnement requises par vos sélections. C'est le point de conception le plus intéressant du projet : la configuration n'est pas un fichier d'exemple à éditer à la main, elle est produite à partir de vos réponses. Le revers est que le contenu exact de chat.config.ts n'est pas documenté dans le README fourni. On sait qu'il existe, qu'il est généré, et qu'il conditionne l'application, mais pas quelles clés il expose ni comment le modifier après coup. C'est la première chose à inspecter après un scaffolding, avant même de lancer le serveur de développement.

Architecture : un monorepo, quatre applications, une pile imposée

Le dépôt est un monorepo avec une séparation nette : apps/site pour la page d'accueil, apps/chat pour l'application Next.js, apps/docs pour la documentation, packages/cli pour le scaffolding. La pile listée dans le README est longue et cohérente entre elle. Next.js en App Router avec React Server Components, TypeScript, AI SDK pour l'appel aux modèles, AI Gateway de Vercel pour l'accès unifié aux 120+ modèles, Better Auth pour l'authentification, Drizzle ORM sur PostgreSQL, Redis pour le cache et les flux reprenables, Vercel Blob pour le stockage de fichiers, tRPC et Zod pour la couche API, Zustand pour l'état côté client. S'y ajoutent Shadcn/UI, Tailwind, Motion, Pino pour les logs, Langfuse pour l'observabilité des appels LLM, Biome et le preset Ultracite pour le lint et le formatage. Cette cohérence est un avantage réel : les choix sont déjà compatibles. C'est aussi une contrainte, car remplacer un seul élément, par exemple Redis ou l'AI Gateway, suppose de comprendre comment les autres en dépendent. Le README ne décrit pas ces points de couplage.

Les fonctionnalités qui pèsent sur l'architecture

La liste de fonctionnalités du README n'est pas décorative, chaque entrée implique du code serveur. Les flux reprenables (« Resumable Streams: Continue generation after page refresh ») expliquent la présence de Redis : sans stockage intermédiaire côté serveur, une génération interrompue par un rechargement de page est perdue. Le branching, qui permet de dupliquer une conversation pour explorer des variantes, impose un modèle de données où les messages forment un arbre et non une liste. Le partage par lien public ajoute une couche d'autorisation distincte de l'authentification classique. Les pièces jointes (images, PDF, documents en glisser-déposer) passent par Vercel Blob. L'exécution de code en sandbox et la recherche web sont des appels d'outils, ce que le README rattache à AI SDK Tools et au support MCP. Enfin, la possibilité d'empaqueter l'application en binaire macOS, Windows ou Linux via Electron signifie que le code doit rester exécutable hors d'un environnement de navigateur, ce qui n'est pas gratuit en Next.js.

Développement local : le détail des ports par worktree

Le README décrit une organisation peu commune pour le travail en parallèle. La variable CHATJS_DEV_SLOT, définie dans .env.worktree.local, réserve une plage stable de dix ports par worktree. Dans cette plage, le chat utilise l'offset 0, Electron l'offset 1 et le site l'offset 2, valeurs définies dans .worktree-env.json. Le fichier .env.worktree.local est ignoré par Git et maintenu séparé du .env.local géré par Vercel. Le README insiste sur un point : « Run bun dev:info instead of assuming a port. » Les commandes disponibles sont bun dev pour l'application de chat, bun dev:docs pour la documentation, bun dev:info pour afficher les URLs assignées, bun lint pour le lint du workspace et bun test:types pour la vérification de types de l'application de chat. Le gestionnaire de paquets est donc bun, ce qui est un choix à assumer si votre outillage interne est basé sur npm ou pnpm.

Limites et cas où ChatJS est le mauvais outil

La première limite est la dépendance à l'AI Gateway de Vercel pour l'accès aux 120+ modèles. Le README présente cela comme un accès unifié, mais cela signifie qu'un déploiement entièrement auto-hébergé doit traiter cette couche comme un composant à remplacer, et le README ne documente pas de chemin alternatif. La deuxième est la surface d'infrastructure : PostgreSQL, Redis et Vercel Blob sont tous nécessaires pour que les fonctionnalités annoncées fonctionnent. Ce n'est pas un projet qu'on lance avec un simple fichier SQLite. La troisième concerne le versionnement : les releases publiées concernent @chat-js/cli, et les changesets couvrent l'ensemble du dépôt, mais rien dans le matériel fourni n'indique une politique de compatibilité entre une version du CLI et une version ultérieure du code généré. Si vous scaffoldez aujourd'hui, la question de la mise à jour vers la version suivante du template reste ouverte. Enfin, si votre besoin est un composant de chat à insérer dans une application existante, ou une API sans interface, ChatJS est surdimensionné : vous héritez d'un monorepo, d'un schéma de base de données et d'une application Electron dont vous n'aurez pas l'usage.

Alternative : partir de l'AI SDK seul

L'alternative la plus directe est de construire l'application autour de l'AI SDK sans passer par ChatJS. La différence n'est pas une question de qualité mais de périmètre. L'AI SDK fournit la couche d'appel aux modèles et le streaming ; il ne fournit ni authentification, ni schéma de base de données, ni stockage de fichiers, ni flux reprenables, ni interface. Choisir l'AI SDK seul signifie écrire soi-même la persistance des messages, la gestion des sessions, l'arborescence des conversations pour le branching et le stockage des pièces jointes. C'est le bon choix si votre modèle de données de conversation est spécifique, par exemple si les messages sont déjà rattachés à des entités métier dans votre base existante. ChatJS prend le parti inverse : il impose un schéma Drizzle et une organisation de monorepo, en échange de quoi ces briques existent dès le premier jour. La question à se poser n'est donc pas « quelle est la meilleure base » mais « mon modèle de conversation est-il assez standard pour accepter celui de ChatJS ».

Maintenance, licence et coût de mise à jour

Le projet est sous Apache-2.0, une licence permissive qui autorise l'usage commercial, la modification et la redistribution, avec conservation des mentions de copyright et du texte de licence. Le README ne contient aucune clause supplémentaire, mais il ne constitue pas un avis juridique : pour un produit distribué, faites vérifier les obligations de mention par votre équipe juridique. Côté maintenance, le dépôt n'est pas archivé et la dernière poussée date de septembre 2026. Le processus de release repose sur Changesets : chaque paquet modifiable reçoit un changeset, la pull request de version est fusionnée, les paquets publics comme @chat-js/cli sont publiés sur npm et les installeurs de @chat-js/electron partent vers GitHub Releases. Ce fonctionnement signifie que le CLI évolue indépendamment de l'application que vous avez générée. Concrètement, une mise à jour du CLI ne met pas à jour votre code : vous devrez comparer vous-même le template généré avec votre fork, fonctionnalité par fonctionnalité. C'est le coût réel de l'approche, et il est plus élevé qu'une simple mise à jour de dépendance.

Conclusion éditoriale

ChatJS convient aux équipes qui construisent un produit de chat et veulent partir d'une base Next.js complète plutôt que d'un écran vide. Il ne convient pas si vous refusez la dépendance à l'AI Gateway de Vercel, à Better Auth, à Drizzle et à Redis, ou si votre application n'est pas un chat. Avant d'adopter, lancez npx @chat-js/cli@latest create, ouvrez le chat.config.ts généré et vérifiez que les choix d'authentification et de fournisseur correspondent à vos variables d'environnement réelles.

Sources officielles

1. FranciscoMoretti/chat-js on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases