Taylor Fang
Fumadocs
Siamo entusiasti di annunciare il primo progetto a cui abbiamo assegnato una sovvenzione: Fumadocs, creato da Fuma Nama.
Fumadocs è un framework di documentazione per React elegante e flessibile. Il framework si articola in quattro livelli modulari: Core, Content, UI e CLI. Sia l'architettura sia il design visivo nascono dai principi fondamentali di componibilità e semplicità. Ogni library è un insieme di "blocchi costitutivi" che mostrano apertamente il proprio funzionamento, dando agli sviluppatori la possibilità di modificare e creare la documentazione esattamente come la vogliono. Il design visivo unisce componenti eleganti e performanti, curati fin nei minimi dettagli. Il risultato è un'esperienza di lettura velocissima, tanto per le persone quanto per gli LLMs.
Fumadocs è utilizzato da Vercel Turborepo, shadcn/ui, BetterAuth, Unkey e molti altri. Il fatto che ogni sito abbia un aspetto radicalmente diverso è la prova della componibilità di Fumadocs. E naturalmente anche General Translation usa Fumadocs per la propria documentazione!
Fuma Nama, il creatore di Fumadocs, ha riflettuto a fondo sull'esperienza degli sviluppatori. Ogni livello e ogni dettaglio del framework sono stati oggetto di un'attenzione fuori dal comune: dalla strutturazione dei contenuti per la leggibilità, alla riduzione dell'astrazione, fino all'equilibrio tra manutenzione e personalizzabilità.
Abbiamo incontrato Fuma Nama per la sua prima intervista in assoluto, ripercorrendo oltre tre anni di sviluppo di Fumadocs e molti altri anni di lavoro nello sviluppo open-source. (Sapevi che ha finito le scuole superiori solo l'anno scorso?)
Di seguito raccontiamo come Fuma Nama ha imparato a programmare osservando i file di codice, la sua opinione sul "software opinionated", perché le sue libraries adottano un approccio "meno magico", perché l'open-source è globale per natura e la sua filosofia sull'esperienza di lettura della documentazione — con qualche easter egg lungo la strada, come l'origine del suo pseudonimo e l'ispirazione lunare del logo di Fumadocs.
Il vibrante mondo del computer
Fuma Nama è cresciuto a Hong Kong. La sua famiglia comprò un computer quando lui aveva 6 anni. Racconta di aver vagabondato per il World Wide Web da bambino, scoprendo per la prima volta il «vibrante mondo del computer». Il suo modo di intendere il software è incantato e giocoso. Alle elementari mise insieme un gioco sandbox in Unity in cui il player poteva passare dalle automobili agli aerei in paesaggi diversi: un deserto, la luna, una città distrutta, una montagna e una foresta.
L'idea del «software come concetto» arrivò più tardi per Fuma. Imparò invece a programmare modificando videogiochi e facendo reverse engineering. Racconta di aver imparato il C# guardando il codice, modificandolo e poi osservando che cosa cambiava nel gioco.
«È una cosa un po' folle. Ho imparato a programmare dai file. Mi capitava di vedere una montagna di JavaScript e la leggevo», racconta. «Non guardavo nessun tipo di documentazione, solo il codice».
Andando direttamente alla «fonte primaria» (anche se per caso), Fuma è arrivato a comprendere in profondità i principi cognitivi di base. Ha assimilato i concetti mentali che stanno dietro a un framework, più che le etichette associate ai comportamenti. Quando gli si chiede quale sia il suo aspetto preferito dell'architettura software, Fuma indica ancora la vecchia OOP (programmazione orientata agli oggetti) in Java, una scelta di una semplicità quasi radicale.
«L'idea dell'oggetto è molto elegante. Io ragiono in termini di estensione delle classi», dice. «È un modello universale che funziona allo stesso modo in Java, in JavaScript e in molti altri linguaggi con cui capita di lavorare».
Fuma Nama si definisce un «open sourcerer» sul suo sito. Dopo aver imparato il C# da zero, non stupisce che descriva i framework moderni per lo sviluppo web come React.js e Vite come «splendenti e magici». La sua esperienza del software è stregata da un senso di possibilità creativa.
«Mi sento infelice se non tocco il mio editor per un giorno intero», dice Fuma. «Anche quando viaggio, la prima cosa che faccio appena sveglio è aprire il computer e aprire l'editor. A volte non so nemmeno bene cosa sto facendo, ma voglio solo aprire il mio editor».
«Quello che un altro prova nel disegnare, io lo provo nel programmare», dice Fuma.
L'ecosistema open-source
Fuma è profondamente consapevole del fatto che le librerie open-source rappresentano la visione e gli sforzi accumulati di innumerevoli sviluppatori.
«È interessante poter mettere le mani su tutte queste idee nate dal confronto tra tante persone e da tantissimo impegno», ha raccontato Fuma Nama. «È come sentire la natura e il pianeta. Puoi davvero percepire le persone di tutto il mondo».
«Per esempio, il Server Component [di React] ha richiesto molte menti brillanti. Il processo RFC ha coinvolto tantissimi sviluppatori insieme ai membri del core team di React», ha detto, riferendosi al processo Request For Comments.
Quando Fuma ha iniziato a costruire quello che sarebbe diventato Fumadocs, all'inizio lo aveva chiamato «Next-docs».
«Pensavo che sarebbe stato divertente creare il framework di documentazione ufficiale di Next.js, un'ambizione piuttosto folle», ha detto. «Ma era un esperimento, proprio quando il Server Component era appena uscito, nell'era dell'App Router, ed era un pattern interessante che non avevo ancora provato. Per me il codice in sé è come un giocattolo con cui ho voglia di giocare».
In seguito ha rinominato il suo framework in Fumadocs per non entrare in conflitto con la documentazione ufficiale. (Il soprannome Fuma Nama nasce da un gioco di parole scherzoso sul giapponese ふわふわ, «fuwa fuwa», usato per descrivere qualcosa di leggero e soffice. L'esperienza degli sviluppatori ideale, si potrebbe dire.)
Fumadocs è cresciuto grazie al forte sostegno della comunità open-source. Le risposte che Fuma predilige sono quelle che arrivano sotto forma di riscontri costruttivi.
«Adoro le risposte che contengono una domanda, o qualsiasi cosa che possa aiutarmi a migliorare il framework», ha detto. Fuma cita ancora oggi una issue aperta due anni fa dallo sviluppatore Anthony Shew. Nella sua richiesta di funzionalità, Shew intuisce che l'intento progettuale di Fumadocs tende con decisione verso una visione di «meno magia, più componibilità».
«È stato uno dei primi ad adottare [Fumadocs] in un progetto importante», ha detto Fuma. «Mi ha dato un riscontro prezioso e davvero concreto. Aveva capito davvero gli obiettivi del progetto e ci teneva: per me è stata una sorpresa».
Da allora Fumadocs ha superato le 13.000 stelle su GitHub ed è usato da aziende come Vercel, Unkey, Orama e, non da ultimo, noi stessi. Negli ultimi tre anni Fuma Nama ha continuato a sviluppare e mantenere il framework, investendoci centinaia di ore oltre allo studio e agli altri impegni.
Dietro la ricerca artigianale di Fuma Nama si cela un insieme di filosofie più profonde sui framework per lo sviluppo web e sulla progettazione del software.
Meno astrazione, software meno opinionated
Nella sezione Philosophy della documentazione di Fumadocs, Fuma enuncia la tesi di fondo: Fumadocs è pensato per essere un framework di documentazione che puoi rompere.
Con "rompibile" intende la possibilità per uno sviluppatore di smontare e rimodellare qualsiasi parte del framework. Lo spirito di Fumadocs è servire chi non vuole soltanto una documentazione che funzioni, ma chi vuole costruire "la documentazione perfetta": su misura per le proprie esigenze, preferenze e sensibilità estetica.
"Ci serve un sistema davvero, davvero componibile", ha detto. "Un framework abbastanza completo e allo stesso tempo estremamente componibile". Fumadocs punta a offrire agli sviluppatori mattoncini Lego modulari e comprensibili, utilizzabili in modi molto diversi per costruire siti di documentazione molto diversi.
L'approccio di Fuma nasce da una diagnosi più ampia: i framework web moderni sono troppo astratti. Sembrano "magicamente" facili da usare perché la complessità è nascosta; ma così si offuscano anche la logica sottostante, i meccanismi e gli inevitabili compromessi. Per esempio, gli sviluppatori alle prime armi possono usare la metadata API di Next.js senza avere idea di come funzioni il tag meta, oppure inserire logica in un server component senza sapere quanto costi quel calcolo.
Un eccesso di astrazione impedisce agli sviluppatori di vedere, capire e modificare davvero il codice. Il suo obiettivo con Fumadocs è quindi essere "meno magico". Il framework mette i file delle route nel tuo repository, ti fa creare l'handler di ricerca, ti permette di chiamare il content loader dal tuo codice e può copiare i componenti UI direttamente nella tua base di codice tramite la CLI.
Fuma definisce esplicitamente il framework come non opinionated. Il termine "software opinionated" indica un framework o una library che impone un insieme di convenzioni, guidando gli utenti verso un unico modo "corretto" di costruire. (A volte viene confuso con l'avere semplicemente un'opinione, o considerato come universalmente positivo.) Il software opinionated, con i suoi default marcati e il percorso "giusto" da seguire, si scontra con gli obiettivi di Fuma: componibilità, rompibilità e meno astrazione.
Fumadocs è dunque un framework meno magico e meno opinionated.
Fuma riconosce comunque la necessità di offrire agli sviluppatori usabilità immediata e completezza. Per questo ha progettato la library UI come uno strato più opinionated del framework, con un design visivo di default deciso. In questo modo gli sviluppatori possono creare da subito una documentazione elegante, mantenendo la possibilità di modificare ogni singolo pezzo modulare. (Il che significa che potrebbero anche sostituire interamente la UI con la propria, se lo desiderano.)
"Il problema più difficile di Fumadocs è bilanciare i due estremi degli utenti", ha detto. "Da un lato ci sono gli sviluppatori che non vogliono fare alcuna modifica e vogliono solo partire in fretta e senza complicazioni. Dall'altro ci sono quelli che vogliono personalizzare tutto, al punto che la forma originale è a malapena riconoscibile."
Questo equilibrio è una sfida per la maggior parte dei framework e degli autori di library, ed è solo uno dei tanti compromessi su cui Fuma Nama ha riflettuto a fondo.
Una scatola nera e un compilatore
Distribuire il codice come package, scelta predefinita comune per una library, è stata per Fuma una decisione attentamente ponderata.
«Il package è una specie di scatola nera per la maggior parte degli sviluppatori, a meno che non vadano a leggere il source code», ha detto Fuma. «Certo, puoi comunque modificare il codice applicando una patch. Ma una volta che lo chiudi dentro un package, non sai davvero cosa succede al suo interno».
Il problema si aggrava con la scala. «Più logica inserisci nel package, più è come mettere altro codice nella scatola nera», ha aggiunto.
L'approccio alternativo, il modello shadcn/ui che consiste nel copiare i componenti direttamente nella propria base di codice, evita il problema della scatola nera. Ma porta con sé altri svantaggi.
«Il costo di manutenzione ricade sempre su di te», ha detto. «E ogni volta che il framework migliora o introduce una nuova funzionalità, devi fare un sacco di refactoring del codice. A un certo punto non ha più senso».
Fuma gestisce questo compromesso in Fumadocs introducendo vie di fuga progressive. Il package resta il modello principale, mentre la CLI (ispirata a shadcn/ui) aiuta gli sviluppatori che arrivano ad aver bisogno di una personalizzazione più granulare. La CLI lavora per componente e può scendere ancora più nel dettaglio, estraendo un singolo slot di un layout (per esempio, solo l'indice dei contenuti). La copy del componente appartiene allo sviluppatore e la prop slots la reinserisce nella struttura circostante, così le release future possono continuare ad aggiornarsi dal package Fumadocs senza sovrascriverla.
Dietro le quinte, Fuma Nama cita la CLI come uno dei pezzi più difficili da realizzare. È di fatto un compilatore che deve prendere il componente originale del package e trasformarlo in file autonomi compatibili con il progetto e il framework di destinazione.
«Devi trasformare un componente che funziona all'interno di un package in qualcosa di separato, isolato in un file che possa essere scaricato nella base di codice», spiega. «Ho dovuto imparare tutti i diversi framework e fare moltissimi test per assicurarmi che l'AST fosse corretto». (La trasformazione dell'Abstract Syntax Tree consiste nell'analizzare il file sorgente del componente trasformandolo in un albero, riscriverne i percorsi di import in base alla destinazione e adattarne la sintassi.)
Con la CLI, i quattro livelli modulari del framework sono completi: Content, Core, UI e CLI.
Fuma descrive Fumadocs come «un insieme di utility e plugin MDX». La sua integration preferita è Story, pensata per la documentazione delle library di componenti. Story è l'ambito in cui Fumadocs dà davvero il meglio, dato che i componenti interattivi non possono essere mostrati solo in Markdown, un fattore limitante per i framework di documentazione meno flessibili.
«Anche se ricominciassi da zero, penso che Fumadocs avrebbe probabilmente la stessa forma», ha detto Fuma. È un framework che si può davvero smontare, ed è stato progettato meticolosamente proprio per questo.
Il credo di design di Fumadocs
La filosofia di design di Fuma per la documentazione tende a un'esperienza utente minimalista, con un'attenzione profonda a ogni dettaglio; la sua sensibilità visiva rispecchia la sua convinzione nella semplicità del codice.
«Sono attratto dall'astrazione della forma nell'arte del design. Cerco di trasferirla nei miei progetti, per rappresentare qualcosa a partire da forme geometriche», racconta. «Il logo di Fumadocs è un cerchio che chiamerei la luna, Luna».
«Ho passato moltissimo tempo solo a curare i dettagli. Il layout predefinito è cambiato tantissime volte, con iterazioni davvero minime a ogni versione», dice.
Fuma Nama ritiene che una «UI appariscente e accattivante» sia più adatta a una landing page, mentre le pagine di documentazione dovrebbero concentrarsi sul contenuto e su un'esperienza di lettura semplice.
Il design dell'indice dei contenuti (TOC) è un esempio di aspetto visivo discreto ma profondamente ponderato di Fumadocs.
«Mi sono ispirato allo slider della documentazione di Clerk. Ma volevo farlo in modo diverso e renderlo più bello», spiega. La meccanica dello slider è complessa a causa del rendering server-side. Il server disegna il contorno ma non può misurare il browser, quindi la parte interattiva va ricostruita client-side. Funziona tracciando la forma del contorno come percorso SVG e applicandola come maschera CSS, con un blocco luminoso che scorre dietro di essa, così che l'evidenziazione della «sezione attiva» si sposti lungo la linea.
«Immagino che la gente non se ne accorga», osserva Fuma. Ma i piccoli dettagli meritano comunque attenzione, ed è evidente che la sua cura per le sfumature del design visivo nasce da un'attenzione più ampia all'esperienza di chi sviluppa e di chi legge.
«Spesso non stai solo costruendo la soluzione, la stai progettando», dice. «Devi provare approcci diversi finché non funziona in modo equilibrato».
Software perfetto
La prossima iterazione di Fumadocs Plus includerà una gestione più semplice, per servire meglio sia i principianti sia l'AI. «Meno complessità è molto meglio per l'AI», ha spiegato Fuma. «Perché, come sappiamo, l'AI può davvero allucinare.»
Nota che riceve meno issue rispetto a prima, probabilmente per via degli agents, che non aprono una issue ma aggirano il problema. È diventato più difficile costruire un ciclo di feedback. «Se gli agents non segnalano i bug, io non posso correggerli», ha detto. «Ma continuo a lavorare attivamente a tutti i progetti, mantenendo il numero di issue il più basso possibile.»
Accoglie volentieri i contributi della comunità open-source. «Se vuoi contribuire con una funzionalità o qualsiasi altra cosa ai miei repo, apri semplicemente una issue e di' che vuoi contribuire», ha detto. «Sarò felice di farne la review.»
«Spero che Fumadocs diventi il framework di documentazione per il web», ha detto. «E voglio continuare a renderlo lo standard per la UI.»
Fuma sta sviluppando anche altro software open-source: tra i progetti in sviluppo attivo ci sono tegami, uno strumento per gestire changelog e versioning, e fumadb, un'API per database destinata alle libraries.
«Penso che l'open-source crescerà ancora di più man mano che sempre più aziende inizieranno a riconoscere il valore della comunità open-source e a restituire qualcosa», ha detto. Ha osservato che l'AI sta ridisegnando l'ecosistema, abbassando i costi di manutenzione dei progetti e lasciando più spazio ai maintainer.
Fuma cita Daishi Kato come sua ispirazione nell'open-source, in particolare il suo framework RSC Waku e la library per la gestione dello stato Jotai.
«Waku è davvero sottovalutato. L'idea chiave è che sia molto minimale e composable, ed è per questo che ci ho costruito sopra Fumadocs e molti altri progetti», ha detto. L'affinità filosofica è evidente: il sito di Waku descrive il framework come «leggero» e come una «esperienza di sviluppo divertente».
Fuma ha dedicato moltissimo tempo ai suoi progetti open-source, con un lavoro meticoloso che spesso resta invisibile. Considera tutti i suoi progetti dei tesori e dei cantieri sempre aperti.
«Voglio costruire software perfetto», ha detto. «Zero issue nei miei repository: è più o meno questo il mio obiettivo.» Se il software perfetto esiste, Fuma Nama potrebbe essere proprio la persona in grado di costruirlo.