Nodefony — le framework Node.js fullstack

Vous êtes…

Ou directement : la documentation · les mesures · le dépôt, sous licence Apache 2.0.

L'essentiel en trente secondes

Un framework Node.js fullstack, en TypeScript strict, bâti directement sur les modules natifs de la plateforme. Pensé pour le temps réel : le serveur HTTP et le serveur WebSocket partagent le même contexte de contrôleur.

Trois propriétés le définissent, et chacune se vérifie dans le code plutôt qu'elle ne se raconte : le temps réel de première classe, l'isomorphisme serveur/navigateur, et une application qui sait se décrire à un outil comme à une personne.

Ce qu'est Nodefony

A note on language. Nodefony is written by a French-speaking author. The code — identifiers, public API, types — is in English, because it travels: npm, editor autocompletion, search. The prose — documentation, agent skills, messages — is in French, the language in which the author explains the why most precisely. Coding agents read it without difficulty; human readers may not, and translating the framework’s texts is planned (#378).

Et NestJS ? Nodefony en partage le modèle — injection, décorateurs, modules — et s’en inspire volontiers. Ses priorités portent ailleurs : une même route sert HTTP et WebSocket, avec la même session et le même pare-feu ; et l’application est pensée pour être lue par un agent de code — générateurs pilotables, catalogue, AGENTS.md dérivé du projet. Deux frameworks, deux accents : le bon choix dépend de ce que votre projet met en avant.

État — version 10.0.0 · préversion 10.0.0-beta.5 en ligne, sous le canal beta uniquement : npm install nodefony sert toujours la 7.0.2 (JavaScript), et le fera jusqu’à la sortie stable · branche par défaut main (dernière publication), développement sur dev · ~7 700 tests quand toute l’infrastructure répond (npm run test:all).

⚠️ Ce dépôt est l’atelier du framework, pas ce qu’une application installe — agent : AGENTS.md. Pour juger le produit, lire une application générée (github.com/nodefony/nodefony, sortie brute de create app) ou en générer une : npm create nodefony@beta <app>.

Nodefony en bref

Nodefony est un framework serveur fullstack pour Node.js, écrit en TypeScript strict et bâti directement sur les modules natifs de la plateforme — node:http, node:http2, WebSocket. Il apporte un noyau à injection de dépendances qui donne à chaque requête son propre conteneur, un système de modules, un pare-feu applicatif, une persistance portable, une console d’administration et la construction des frontends.

Sa particularité tient en une propriété : le WebSocket n’y est pas un ajout. C’est un transport de première classe, servi par le même pipeline, la même table de routes et la même sécurité que le HTTP. Une application temps réel s’y écrit comme une application web ordinaire.

npm create nodefony@beta mon-app

Chaque requête a son propre conteneur

Un processus Node sert des centaines de requêtes entrelacées : pendant que l’une attend sa base de données, une autre s’exécute. Nodefony donne donc à chaque requête son propre conteneur de services, posé comme un calque sur celui de l’application.

• Le mécanisme. Le conteneur du kernel est la carte ; à l’entrée d’une requête, le pipeline pose un calque (enterScope) — un objet dont le prototype est la carte. À la fin, leaveScope le jette.
• Ce qu’on y fait. On lit toute la carte à travers le calque (les services de l’application s’héritent) ; on n’écrit que sur son calque. Deux requêtes concurrentes ont deux calques et ne se voient jamais ; rien de ce qui est posé sur un calque ne survit à la requête.
• Le fil qui relie tout : AsyncLocalStorage. Chaque requête s’exécute dans une bulle ALS de Node (RequestContext) : son identifiant, l’utilisateur, la trace W3C et le calque suivent chaque await, jusque dans un service ou un adaptateur ORM, sans qu’on les passe d’appel en appel.
• Comment on l’atteint. Depuis n’importe quel code de la requête, sans passer le contexte : RequestContext.getScope() rend le calque courant (ou undefined), requireScope() lève en nommant la cause. La bulle ALS de la requête dit lequel est le tien. Un hook onAfterResponse le voit encore ouvert ; une promesse non attendue qui continue après la réponse, non.
• HTTP et WebSocket. Une requête HTTP = un calque. Une connexion WebSocket = un calque, partagé par tous ses messages, concurrents compris.
• Des services par requête. @injectable({ scope: "request" }) donne un exemplaire par requête, créé seulement si la requête le demande, et nettoyé (clean(), dans l’ordre inverse des créations) à sa fermeture. Un singleton qui en dépendrait est refusé dès le démarrage, plutôt que de devenir lui-même, sans qu’on l’ait écrit, un service par requête.
• Le coût, avec son décor. Poser puis jeter un calque ≈ 1,43 µs (sonde dans le serveur, un processus en production, paires alternées) ; une requête qui ne résout aucun service par requête ne paie rien de plus.

import { Service, injectable, RequestContext } from "nodefony";
import type { Scope } from "nodefony";

@injectable({ name: "requestStamp", scope: "request" })
export class RequestStamp extends Service {
  readonly requestId: string;
  constructor(scope: Scope) {
    super("requestStamp", scope, false); // un exemplaire pour CETTE requête
    this.requestId = RequestContext.getRequestId() ?? "?";
  }
}

Le détail — les trois durées de vie, l’accès par RequestContext, les pièges : Injection & portées.

Les frontends ne sont pas laissés dehors. Nodefony pilote Vite : en développement il démarre les serveurs de développement — React, Vue, Angular, Svelte —, les surveille, relaie leur rechargement à chaud et sert leurs pages ; en production il construit les bundles et les distribue. Une application peut en porter plusieurs, chacun monté sur sa route.

Le socle, lui, est isomorphe : le même paquet s’importe côté serveur et côté navigateur. Le client temps réel, les règles d’autorisation, les types d’une ressource sont écrits une fois et s’exécutent là où ils servent — une règle corrigée l’est des deux côtés.

Démarrage

Une préversion 10.0.0-beta.5 est en ligne sous le canal beta. Une bêta n’est pas une version stable : une rupture reste possible d’une bêta à la suivante — chacune est alors annoncée en tête du CHANGELOG — et elle n’est pas destinée à la production. Elle s’installe en nommant ce canal :

npm create nodefony@beta mon-app
cd mon-app
npm run dev

Le canal se nomme tant que la 10 n’est pas stable : c’est lui qui garantit de recevoir la préversion, et non la 7.0.2 que npm install nodefony sert encore — la version JavaScript d’avant, sans rapport avec ce que cette page décrit.

L’application répond sur http://127.0.0.1:5151 — ou le premier port libre, annoncé au démarrage — et la console d’administration sur /nodefony.

À quoi ressemble ce que la commande produit : github.com/nodefony/nodefony. Ce dépôt n’est pas une démonstration écrite à la main pour la vitrine — c’est la sortie littérale de nodefony create app --preset complete --frontend react, poussée telle quelle et régénérée à chaque publication. Base de données et migration initiale, sécurité et comptes, temps réel, console d’administration, front React, infra docker de développement, chaîne d’intégration continue : tout ce que vous y lisez a été engendré, rien n’y a été retouché. C’est le moyen le plus court de juger le code qu’on aura à maintenir, avant d’installer quoi que ce soit.

Pour travailler sur le framework lui-même, c’est le dépôt qu’on clone :

git clone https://github.com/nodefony/nodefony-core.git
cd nodefony-core
npm install && npm run build
npm run dev

Générer du code — une application, un module, un contrôleur, une entité et toute sa chaîne :

npx nodefony create module blog --frontend react
npx nodefony create entity Article title:string body:text views:int
npx nodefony create controller admin --kind rest --role ROLE_ADMIN

Chaque générateur montre le plan et le diff avant d’écrire quoi que ce soit. Un refus ne laisse rien derrière lui. Il publie aussi son catalogue en JSON et accepte ses réponses par fichier : la même porte sert la personne au terminal, la console d’administration et un agent.

Ce qu’il y a dans la boîte

Par défaut, un processus Node égale une instance : le passage à l’échelle revient à l’orchestrateur, et les journaux partent sur la sortie standard. Sans orchestrateur, nodefony cluster -w N démarre N workers isolés, relancés s’ils tombent.

État du projet

Le cœur — serveurs, routage, sécurité, temps réel, persistance, console d’administration, construction des frontends — est couvert par des suites de tests exécutables sur infrastructure réelle (npm run test:all), et le dépôt versionne des seuils de fuite mémoire et de charge opposables à chaque exécution.

Ce que ça donne en charge. À travail égal — mêmes journaux, même contexte de requête, mêmes en-têtes de sécurité, même protection CSRF —, Nodefony se tient dans la même zone qu’Express et NestJS munis des mêmes intergiciels : entre 93,6 et 112,7 % de leur débit sur une route qui ne fait rien (21 686 requêtes/s, p99 4,4 ms sur la machine de référence), entre 95,9 et 96,7 % sur une route qui lit et écrit une base — pour une résolution de banc de 3 %. Quatre-vingt-huit minutes de charge continue et 97,5 millions de requêtes laissent le tas, l’empreinte mémoire et le rss plats : 0,021 Mo par million de requêtes. La page de mesures de la version courante — peut-on partir en production ? — porte le comparatif, la tenue dans la durée, le dimensionnement d’un pod et un calculateur ; elle nomme aussi ce que ces chiffres ne prouvent pas. Le dossier docs/performance/ donne le protocole, les scripts qui rejouent chaque chiffre et les instruments qui ont menti avant qu’on s’en aperçoive — aucun absolu pris derrière un chemin virtualisé n’est transposable.

Ce qu’il faut savoir avant de bâtir dessus : les versions JavaScript historiques (≤ 7.x) ne reçoivent plus de correctifs. Projet libre, développé bénévolement par une seule personne.

Licence Apache 2.0 — permissive, avec concession de brevet explicite. Christophe Camensuli · ccamensuli@gmail.com

D'où ça vient — de 2017 à la réécriture

Nodefony est publié depuis 2017, en JavaScript, et a mûri jusqu'à sa version 7 : des applications réelles tournent encore dessus. Fin 2023, plutôt qu'une migration par petits pas, le choix a été fait d'une réécriture complète en TypeScript — en gardant les concepts, en jetant tout le reste.

Pourquoi ? Parce qu'un framework ne se contente pas d'exécuter du code : il contraint celui qu'on écrit contre lui. Une couche de types posée après coup décrit ce que le code fait ; elle ne garantit rien. Chaque parti pris de la réécriture ferme une porte :

Le pari : un transport n'est pas une architecture

La plupart des piles traitent le WebSocket comme une annexe : une seconde table de routes, une seconde pile d'authentification, une passerelle entre les deux. Nodefony refuse cette séparation. La pseudo-méthode WEBSOCKET est un verbe comme GET :

@controller("/api/blog")
class BlogController extends Controller {
  @route("blog-index", { path: "", method: "GET" })
  async index(@CurrentUser() user?: { identifier?: string }) {
    return this.renderJson({ hello: "blog", who: user?.identifier ?? "anonyme" });
  }

  // Même classe, même décorateur : seul le transport déclaré change.
  @route("blog-echo", { path: "/echo", requirements: { methods: ["WEBSOCKET"] } })
  async echo(message: string | Buffer | null) {
    return this.renderJson({ echo: message?.toString() ?? null });
  }
}

L'isomorphisme — et pourquoi le cœur reste en TypeScript

Le client n'est pas une bibliothèque à part, publiée séparément et rattrapée à chaque version : il vit dans le même paquet que le serveur et partage ses types. Le contrat d'un canal, la forme d'un message, la hiérarchie des rôles s'écrivent une fois.

Un bouton masqué faute de rôle l'est par la même logique que celle qui refusera l'appel. Il n'y a pas deux vérités à synchroniser.

Prêt pour les agents — ce qui tranche pour la suite

Une application est aujourd'hui écrite à deux mains : la personne, et l'agent qu'elle pilote. Un agent lâché dans un projet bâti sur un framework qu'il connaît mal invente — et il invente du plausible : un CRUD écrit à la main là où un générateur existait, un import direct du driver de base qui contourne la façade, une socket bas niveau là où le framework offre un canal. Ce code compile. Il passe même les tests. Il a vieilli avant d'être relu.

La réponse n'est pas un assistant intégré, c'est de rendre l'application capable de se décrire :

Aucun framework backend Node n'offre aujourd'hui d'équivalent officiel. C'est un espace vide, et c'est délibérément là que Nodefony se place.

Ce que les suites éprouvent — les angles, pas seulement le nombre

Un compte de tests ne dit rien de ce qu'ils regardent. Ces chiffres sont comptés dans le dépôt au moment de la génération de cette page, fichier par fichier.

S'y ajoutent 12 flux d'intégration continue — analyse statique de sécurité, gate mémoire, suites ORM sur plusieurs moteurs, bout-en-bout autonomes, contrôle avant publication et installation à blanc des paquets depuis leurs archives.

La matrice — ce qui est couvert, domaine par domaine

Calculé depuis le dépôt au moment de la génération de cette page : pour chaque domaine, le code, les suites de tests, la documentation destinée aux humains, et la fiche d'entrée du paquet.

La sécurité s'éprouve par l'attaque, pas par la lecture

Le pare-feu découpe l'application en zones, chacune avec sa chaîne d'authentification, et il refuse plutôt que d'ouvrir : une configuration invalide capture le trafic et répond 401.

Équipe rouge, équipe bleue

« Le login fonctionne » ne prouve rien. Les campagnes se mènent en deux passes, et l'ordre est le cœur du dispositif :

1. Passe rouge — la menace d'abord. La matrice d'attaque est construite depuis les standards et les faiblesses connues avant d'avoir lu le code. C'est un garde-fou contre son propre biais : qui lit l'implémentation en premier ne teste que ce qu'elle prévoit, et rate précisément ce qu'elle a oublié.
2. Passe bleue — le code ensuite. On lit l'implémentation, on couvre les branches restantes, on regarde les chemins que la passe rouge n'imaginait pas.
3. Le cycle. Faille trouvée → corrigée → re-prouvée par un test qui échouait avant elle. Un correctif sans son test de non-retour ne compte pas comme corrigé.

Ce qui distingue ces attaques d'un scan générique : beaucoup visent des surfaces propres à cette architecture — les portées de l'injection de dépendances, les messages du pipeline WebSocket partagé, le jeton porté par le contexte asynchrone, les zones du pare-feu et leurs contournements. Aucun outil sur étagère ne connaît ces surfaces : il faut concevoir les attaques.

Le framework se regarde tourner

Une console d'administration est livrée avec le framework : topologie du runtime, journaux en direct avec rejeu, suivi d'une requête de bout en bout par son identifiant, schéma de la base, graphe des classes par module, gouvernance de la sécurité, et les générateurs de code pilotables à la souris — la sortie diffusée comme un terminal.

Chaque requête porte un identifiant propagé dans tout le pipeline : la console rejoue son trajet complet — phases, requêtes de base de données, décisions du pare-feu.

Même principe pour les générateurs de code : ils publient leur catalogue, montrent le plan et le diff avant d'écrire quoi que ce soit, et acceptent leurs réponses par fichier. Un refus ne laisse rien derrière lui.

Performance : la question honnête

Le framework fait à chaque requête ce qu'une pile minimale ne fait pas : contexte asynchrone corrélé, identifiant de requête, en-têtes de sécurité, contrôle CSRF, résolution de zone de pare-feu. Comparer sans ce travail ne compare rien. Les constantes ci-dessous servent à dimensionner, pas à gagner un concours.

Ce que le dépôt garantit à chaque commit

Les preuves existent, et elles sont rejouables

Chaque affirmation de ce support s'adosse à un artefact produit par le dépôt lui-même, pas à une déclaration d'intention. Ces rapports se régénèrent par une commande :

Ce qui manque — dit avant qu'on le demande

Dire les manques n'est pas une précaution rhétorique : c'est ce qui rend le reste vérifiable. Un dossier sans zone d'ombre décrit rarement un vrai logiciel.

La direction

La suite est une couche d'agents construite sur ce socle : le même pipeline, la même sécurité, le même temps réel — et une application qui sait déjà se décrire à une machine.

Rien de cette couche n'est promis dans la version courante. Ce qui est acquis, en revanche, c'est le terrain sur lequel elle se posera : un plan de données auto-décrit, un graphe symbolique du code, un générateur pilotable par fichier, et un transport duplex qui fait du flux un cas ordinaire plutôt qu'un montage.