Taylor Fang
Fumadocs
Nous sommes ravis d'annoncer le premier projet bénéficiaire de notre programme de subventions : Fumadocs, créé par Fuma Nama.
Fumadocs est un framework de documentation React à la fois élégant et flexible. Il repose sur quatre couches modulaires : Core, Content, UI et CLI. L'architecture comme le design visuel découlent des principes fondateurs de composabilité et de simplicité. Chaque bibliothèque est un ensemble de « briques » qui exposent leur fonctionnement, permettant aux développeurs de modifier et de créer leur documentation exactement comme ils l'entendent. Le design visuel réunit des composants élégants et performants, avec un soin extrême du détail. Il en résulte une expérience de lecture ultra-rapide, aussi bien pour les humains que pour les LLMs.
Fumadocs est utilisé par Vercel Turborepo, shadcn/ui, BetterAuth, Unkey et bien d'autres. Le fait que chacun de ces sites ait une apparence radicalement différente témoigne de la composabilité de Fumadocs. Et bien sûr, General Translation utilise Fumadocs pour sa propre documentation !
Fuma Nama, le créateur de Fumadocs, a mené une réflexion approfondie sur l'expérience développeur. Un soin hors du commun a été apporté à chaque couche et à chaque détail du framework : de la structuration du contenu pour en faciliter la lecture à la réduction de l'abstraction, en passant par l'équilibre entre maintenabilité et personnalisation.
Nous avons échangé avec Fuma Nama à l'occasion de sa toute première interview, qui revient sur plus de trois ans de développement de Fumadocs et sur de nombreuses années de contribution au développement open-source. (Saviez-vous qu'il a terminé le lycée l'an dernier ?)
Nous verrons ci-dessous comment Fuma Nama a appris à coder en lisant des fichiers de code, ce qu'il pense des « logiciels opinionated », pourquoi ses bibliothèques adoptent une approche « moins magique », en quoi l'open-source est intrinsèquement mondial, et sa philosophie de l'expérience de lecture d'une documentation — avec quelques surprises en chemin, comme l'origine de son pseudonyme ou l'inspiration lunaire du Logo de Fumadocs.
Le monde foisonnant de l'ordinateur
Fuma Nama a grandi à Hong Kong. Sa famille a acheté un ordinateur alors qu'il avait 6 ans. Il raconte avoir arpenté le World Wide Web enfant, où il a découvert pour la première fois le « monde foisonnant de l'ordinateur ». Son rapport au logiciel est fait d'émerveillement et de jeu. À l'école primaire, il a bricolé un jeu bac à sable sous Unity dans lequel le joueur pouvait passer d'une voiture à un avion à travers différents décors : un désert, la Lune, une ville détruite, une montagne et une forêt.
L'idée du « logiciel comme concept » n'est venue à Fuma que plus tard. Il a d'abord appris à coder en moddant des jeux vidéo et en pratiquant la rétro-ingénierie. Il raconte avoir assimilé le C# en regardant du code, en le modifiant, puis en observant ce qui changeait dans le jeu.
« C'est un peu fou. J'ai appris à coder à partir de fichiers. Je tombais sur un énorme tas de JavaScript et je le lisais », dit-il. « Je ne consultais aucune documentation, juste le code lui-même. »
En allant directement à « la source primaire » (même si c'était par accident), Fuma a fini par comprendre en profondeur les principes cognitifs fondamentaux. Il a saisi les concepts mentaux qui sous-tendent un framework, plutôt que les étiquettes accolées à des comportements. Interrogé sur son aspect préféré de l'architecture logicielle, Fuma cite encore et toujours la bonne vieille POO (programmation orientée objet) en Java, un choix d'une simplicité presque radicale.
« L'idée de l'objet est très élégante. Je pense en termes d'extension de classes », dit-il. « C'est un modèle universel qui fonctionne de la même façon en Java, en JavaScript et dans bien d'autres langages que l'on manipule. »
Fuma Nama se décrit comme un « open sourcerer » sur son site web. Après avoir appris le C# en partant de zéro, rien d'étonnant à ce qu'il qualifie les frameworks web modernes comme React.js et Vite de « brillants et magiques ». Sa manière de vivre le logiciel est habitée par un sentiment de possibilité créative.
« Je me sens malheureux si je n'ai pas touché à mon éditeur de toute une journée », dit Fuma. « Même en voyage, la première chose que je fais au réveil, c'est d'ouvrir mon ordinateur et mon éditeur. Parfois je ne sais même pas vraiment ce que je fais, mais j'ai simplement envie d'ouvrir mon éditeur. »
« Ce que quelqu'un d'autre ressent en dessinant, je le ressens en codant », conclut Fuma.
L'écosystème open-source
Fuma est pleinement conscient que les bibliothèques open-source incarnent la vision et les efforts accumulés d'une multitude de développeurs.
« C'est fascinant de pouvoir mettre la main sur toutes ces idées conçues par tant de gens et au prix de tant d'efforts », déclare Fuma Nama. « C'est comme ressentir la nature et le monde entier. On sent vraiment la présence de gens des quatre coins du globe. »
« Par exemple, le Server Component [de React] a mobilisé de nombreux esprits brillants. Le processus de RFC faisait que beaucoup de développeurs y participaient, aux côtés des membres de l'équipe centrale de React », dit-il, en référence au processus Request For Comments.
Lorsque Fuma a commencé à développer ce qui allait devenir Fumadocs, il l'avait d'abord baptisé « Next-docs ».
« Je trouvais l'idée plutôt amusante de créer le framework de documentation officiel de Next.js, ce qui était une ambition un peu folle », raconte-t-il. « Mais c'était une expérimentation, juste au moment où le Server Component venait de sortir, à l'ère de l'App Router, et c'était une approche intéressante que je n'avais pas encore essayée. Pour moi, le code lui-même est comme un jouet que j'ai envie d'essayer. »
Il a ensuite renommé son framework en Fumadocs pour éviter toute confusion avec la documentation officielle. (Le pseudonyme Fuma Nama vient d'un jeu de mots fantaisiste sur le japonais ふわふわ, « fuwa fuwa », qui décrit quelque chose de léger et moelleux. L'expérience développeur idéale, pourrait-on dire.)
Fumadocs s'est développé grâce au soutien indéfectible de la communauté open-source. Les réactions que Fuma préfère sont celles qui prennent la forme de retours constructifs.
« J'adore les réponses accompagnées d'une question, ou tout ce qui peut m'aider à améliorer le framework », dit-il. Fuma cite encore aujourd'hui une issue ouverte il y a deux ans par le développeur Anthony Shew. Dans sa demande de fonctionnalité, Shew relève que le parti pris de conception de Fumadocs penche nettement vers une vision « moins de magie, plus de composabilité ».
« Il a été l'un des premiers à adopter [Fumadocs] sur un projet d'envergure », explique Fuma. « Il m'a donné des retours précieux et vraiment concrets. Il comprenait réellement les objectifs du projet et y tenait, ce qui m'a surpris. »
Fumadocs a depuis dépassé les 13 000 étoiles sur GitHub, et est utilisé par des entreprises comme Vercel, Unkey, Orama, et nous-mêmes. Au cours des trois dernières années, Fuma Nama a continué à développer et à maintenir le framework, y investissant des centaines d'heures en plus de ses études et de ses autres obligations.
Derrière le souci du travail bien fait de Fuma Nama se cache tout un ensemble de réflexions plus profondes sur les frameworks de développement web et la conception logicielle.
Moins d'abstraction, des logiciels moins dogmatiques
Dans la section Philosophy de la documentation de Fumadocs, Fuma énonce sa thèse centrale : Fumadocs est conçu pour être un framework de documentation que l'on peut casser.
Par « cassable », il entend la possibilité pour un développeur de démonter et de remodeler n'importe quelle partie du framework. L'esprit de Fumadocs est de servir ceux qui ne veulent pas simplement une documentation qui fonctionne, mais qui veulent construire « la documentation parfaite » : taillée sur mesure pour leurs besoins, leurs préférences et leur sens de l'esthétique.
« Il nous faut un système vraiment, vraiment composable », explique-t-il. « Un framework suffisamment complet tout en étant extrêmement composable. » Fumadocs cherche à offrir aux développeurs des Lego modulaires et compréhensibles, qu'ils peuvent assembler de manières très différentes pour bâtir des sites de documentation très différents.
L'approche de Fuma découle d'un constat plus large : les frameworks web modernes sont trop abstraits. Ils semblent « magiquement » faciles à utiliser parce que la complexité est masquée ; mais cela occulte aussi la logique sous-jacente, les mécanismes et les compromis inévitables. Par exemple, un développeur débutant peut utiliser la metadata API de Next.js sans savoir comment fonctionne la balise meta, ou placer de la logique dans un server component sans avoir la moindre idée du coût de calcul.
Trop d'abstraction empêche les développeurs de réellement voir, comprendre et modifier le code. Avec Fumadocs, son objectif est donc d'être « moins magique ». Le framework place les fichiers de route dans votre repository, vous fait créer le search handler, vous laisse appeler le content loader depuis votre propre code, et peut copier les composants d'UI directement dans votre codebase via la CLI.
Fuma définit explicitement le framework comme non dogmatique. Le terme « opinionated software » désigne un framework ou une bibliothèque qui impose un ensemble de conventions et oriente ses utilisateurs vers une seule « bonne » façon de construire. (On le confond parfois avec le simple fait d'avoir un point de vue, ou on l'emploie comme un qualificatif toujours positif.) Les logiciels dogmatiques, avec leurs valeurs par défaut fortes et leur voie « juste », se heurtent aux objectifs de Fuma : composabilité, cassabilité et moindre abstraction.
Fumadocs est donc un framework moins magique et moins dogmatique.
Fuma reconnaît malgré tout la nécessité d'aider les développeurs sur le plan de l'utilisabilité immédiate et de l'exhaustivité. À cette fin, il a conçu la bibliothèque d'UI comme une couche plus dogmatique du framework, dotée d'un design visuel par défaut affirmé. Les développeurs peuvent ainsi créer d'emblée une documentation élégante tout en conservant la possibilité de modifier chaque brique modulaire. (Ce qui signifie qu'ils pourraient, s'ils le souhaitent, y substituer entièrement leur propre UI.)
« Le problème le plus difficile de Fumadocs, c'est de concilier deux extrêmes chez les utilisateurs », dit-il. « D'un côté, les développeurs qui ne veulent apporter aucune modification et souhaitent simplement démarrer vite et facilement. De l'autre, ceux qui veulent tout personnaliser, au point qu'on reconnaît à peine la forme d'origine. »
Cet exercice d'équilibriste est un défi pour la plupart des auteurs de frameworks et de bibliothèques, et ce n'est là qu'un des nombreux compromis auxquels Fuma Nama a longuement réfléchi.
Une boîte noire et un compilateur
Distribuer du code sous forme de paquet, choix par défaut courant pour une bibliothèque, a fait l'objet d'une réflexion approfondie de la part de Fuma.
« Le paquet est une sorte de boîte noire pour la plupart des développeurs, à moins qu'ils n'aillent lire le code source », explique Fuma. « Bien sûr, vous pouvez toujours modifier le code en le patchant. Mais une fois qu'il est enfermé dans un paquet, vous ne savez plus vraiment ce qui se passe à l'intérieur. »
Le problème s'aggrave à mesure que le projet grandit. « Plus vous mettez de logique dans le paquet, plus vous mettez de code dans la boîte noire », précise-t-il.
L'approche alternative, le modèle shadcn/ui qui consiste à copier les composants directement dans votre codebase, évite le problème de la boîte noire. Mais elle comporte ses propres inconvénients.
« Le coût de maintenance vous revient toujours », dit-il. « Et chaque fois que le framework évolue ou ajoute une fonctionnalité, vous devez refactoriser énormément de code. À un moment donné, cela n'a plus de sens. »
Fuma compose avec ce compromis dans Fumadocs en y intégrant des échappatoires progressives. Le paquet reste le modèle principal, tandis que le CLI (inspiré de shadcn/ui) vient en aide aux développeurs qui ont besoin d'une personnalisation plus fine. Le CLI fonctionne composant par composant, et peut même descendre plus bas en extrayant un seul slot d'une mise en page (par exemple, uniquement la table des matières). La copie du composant appartient au développeur et la prop slots la réinsère dans la structure environnante : les futures versions peuvent ainsi continuer à recevoir les mises à jour du paquet Fumadocs sans l'écraser.
En coulisses, Fuma Nama cite le CLI comme l'un des éléments les plus difficiles à construire. Il s'agit en réalité d'un compilateur qui doit prendre le composant d'origine du paquet et le transformer en fichiers autonomes compatibles avec le projet et le framework de destination.
« Vous devez reprendre un composant fonctionnel dans un paquet et le transformer en quelque chose de séparé, isolé dans un fichier qui peut être téléchargé dans la codebase », explique-t-il. « J'ai dû apprendre tous les frameworks et faire beaucoup de tests pour m'assurer que l'AST était correct. » (La transformation de l'arbre syntaxique abstrait consiste à analyser le fichier source du composant sous forme d'arborescence, à réécrire ses chemins d'import pour correspondre à la destination, et à en adapter la syntaxe.)
Avec le CLI, les quatre couches modulaires du framework sont complètes : Content, Core, UI et CLI.
Fuma décrit Fumadocs comme « un ensemble d'utilitaires et de plugins MDX ». Son intégration préférée est Story, conçue pour la documentation de bibliothèques de composants. C'est avec Story que Fumadocs brille vraiment, car les composants interactifs ne peuvent pas être mis en valeur en Markdown seul, ce qui constitue une limite pour les frameworks de documentation moins flexibles.
« Même si je repartais de zéro, je pense que Fumadocs aurait probablement la même forme », affirme Fuma. C'est un framework qui peut réellement être cassé, et qui a été méticuleusement conçu pour l'être.
Le credo de conception de Fumadocs
La philosophie de conception de Fuma pour la documentation tend vers une expérience utilisateur minimaliste, avec une attention poussée à chaque détail ; sa sensibilité graphique rejoint sa conviction qu'il faut privilégier la simplicité dans le code.
« L'abstraction des formes dans l'art graphique m'attire. J'essaie d'intégrer cela dans mes propres créations pour représenter quelque chose à partir de formes géométriques », explique-t-il. « Le logo de Fumadocs est un cercle que j'appellerais la lune, Luna. »
« J'ai passé beaucoup de temps à peaufiner les détails. La mise en page par défaut a été modifiée de nombreuses fois, avec de toutes petites itérations à chaque version », précise-t-il.
Fuma Nama estime qu'une « UI accrocheuse et sophistiquée » convient davantage à une page d'accueil, tandis que les pages de documentation devraient se concentrer sur le contenu et une expérience de lecture simple.
La conception de la table des matières (TOC) illustre bien cet aspect visuel discret mais mûrement réfléchi de Fumadocs.
« Je me suis inspiré du curseur de la documentation de Clerk. Mais je voulais procéder différemment et le rendre plus beau », raconte-t-il. Le fonctionnement du curseur est délicat en raison du rendu côté serveur. Le serveur dessine le contour mais ne peut pas prendre les mesures du navigateur : la partie interactive doit donc être reconstruite côté client. Le principe consiste à tracer la forme du contour sous forme de chemin SVG, puis à l'appliquer comme masque CSS, avec un bloc lumineux qui glisse derrière lui, de sorte que la mise en évidence de la « section active » se déplace le long de la ligne.
« J'imagine que les gens ne le remarquent pas forcément », observe Fuma. Mais ces petits détails méritent d'être soignés, et son attention aux nuances du design visuel découle manifestement du soin plus large qu'il apporte à l'expérience des développeurs et des lecteurs.
« Bien souvent, on ne se contente pas de créer la solution, on la conçoit », conclut-il. « Il faut essayer différentes approches jusqu'à ce que le résultat soit équilibré. »
Le logiciel parfait
La prochaine itération de Fumadocs Plus proposera une prise en main plus simple, afin de mieux servir les débutants comme l'IA. « Moins de complexité, c'est bien mieux pour l'IA », explique Fuma. « Parce que, comme on le sait, l'IA peut vraiment halluciner. »
Il constate qu'il reçoit moins d'issues qu'auparavant, probablement à cause des agents, qui n'ouvrent pas d'issue mais contournent le problème. Il est devenu plus difficile de créer une boucle de rétroaction. « Si les agents ne signalent pas les bugs, je ne peux pas les corriger », dit-il. « Mais je continue de travailler activement sur tous les projets et de garder le nombre d'issues aussi bas que possible. »
Il accueille volontiers les contributions de la communauté open-source. « Si vous voulez apporter une fonctionnalité ou quoi que ce soit à mes repos, ouvrez simplement une issue en disant que vous souhaitez contribuer », dit-il. « Je serai ravi de la passer en review. »
« J'espère que Fumadocs deviendra le framework de documentation du web », dit-il. « Et je veux continuer à en faire le standard pour l'UI. »
Fuma développe également d'autres logiciels open-source, notamment tegami, en développement actif, un outil pour gérer les changelogs et la gestion des versions, ainsi que fumadb, une API de base de données pour les bibliothèques.
« Je pense que l'open-source va prendre de l'ampleur à mesure que de plus en plus d'entreprises reconnaîtront la communauté open-source et lui rendront la pareille », dit-il. Il souligne que l'IA remodèle l'écosystème, en réduisant le coût de maintenance des projets et en laissant plus de marge aux mainteneurs.
Fuma cite Daishi Kato comme son inspiration open-source, en particulier son framework RSC Waku et sa bibliothèque de gestion d'état Jotai.
« Waku est vraiment sous-estimé. L'idée clé, c'est qu'il est très minimal et composable, et c'est pourquoi j'ai bâti Fumadocs et bien d'autres projets par-dessus », dit-il. Leur alignement philosophique est manifeste : le site de Waku décrit le framework comme « léger » et offrant une « expérience développeur agréable ».
Fuma a consacré un temps immense à ses projets open-source, au prix d'efforts minutieux qui restent souvent invisibles. Il considère tous ses projets comme ses trésors et comme des chantiers permanents.
« Je veux construire un logiciel parfait », dit-il. « Zéro issue sur mes dépôts, c'est un peu mon objectif. » Si le logiciel parfait existe, Fuma Nama pourrait bien être celui qui le construira.