Taylor Fang
Fumadocs
Nos entusiasma anunciar el primer proyecto beneficiario de nuestras becas: Fumadocs, creado por Fuma Nama.
Fumadocs es un framework de documentación en React tan hermoso como flexible. El framework tiene cuatro capas modulares: Core, Content, interfaz de usuario y CLI. Tanto la arquitectura como el diseño visual nacen de sus principios filosóficos fundamentales: la componibilidad y la simplicidad. Cada biblioteca es un conjunto de «bloques de construcción» que dejan a la vista cómo funcionan, lo que permite a quienes desarrollan modificar y crear documentación exactamente como la quieren. El diseño visual integra componentes elegantes y de alto rendimiento con una atención minuciosa al detalle. Es una experiencia de lectura vertiginosa, tanto para personas como para LLMs.
Fumadocs es utilizado por Vercel Turborepo, shadcn/ui, BetterAuth, Unkey y muchos más. Que cada sitio se vea radicalmente distinto es una muestra de la componibilidad de Fumadocs. Y, por supuesto, en General Translation usamos Fumadocs para nuestra propia documentación.
Fuma Nama, el creador de Fumadocs, ha reflexionado a fondo sobre la experiencia de desarrollo. Cada capa y cada detalle del framework han recibido una atención desmedida: desde estructurar el contenido para que sea legible, hasta reducir la abstracción y equilibrar el mantenimiento con la personalización.
Conversamos con Fuma Nama en su primera entrevista, en la que repasamos más de tres años desarrollando Fumadocs y muchos más años trabajando en desarrollo open-source. (¿Sabías que terminó la secundaria apenas el año pasado?)
A continuación, contamos cómo Fuma Nama aprendió a programar mirando archivos de código, su postura sobre el «software opinionado», por qué sus bibliotecas adoptan un enfoque de «menos magia», por qué el open-source es global por naturaleza y su filosofía sobre la experiencia de lectura en la documentación, con algunos huevos de pascua por el camino, como el origen de su seudónimo y cómo la luna inspiró el logotipo de Fumadocs.
El vibrante mundo de la computadora
Fuma Nama creció en Hong Kong. Su familia compró una computadora cuando él tenía 6 años. Escribe sobre sus andanzas por la World Wide Web cuando era niño, donde experimentó por primera vez el “vibrante mundo de la computadora”. Su manera de entender el software es fascinada y lúdica. En la escuela primaria, armó a su modo un juego sandbox en Unity para que el player pudiera alternar entre autos y aviones en distintos paisajes: un desierto, la luna, una ciudad destruida, una montaña y un bosque.
La noción de “software como concepto” le llegó a Fuma más tarde. Aprendió a programar, en cambio, creando mods de videojuegos y haciendo ingeniería inversa. Cuenta que fue aprendiendo C# mirando el código, modificándolo y viendo después qué cambiaba en el juego.
“Es algo bastante disparatado. Aprendí a programar a partir de archivos. Veía un montón enorme de JavaScript y lo leía”, dijo. “No consultaba ningún tipo de documentación, solo el código en sí”.
Al ir directamente a “la fuente primaria” (aunque fuera sin proponérselo), Fuma llegó a comprender a fondo los principios cognitivos más elementales. Asimiló los conceptos mentales que hay detrás de un framework, en lugar de las etiquetas asociadas a los comportamientos. Cuando se le pregunta por su aspecto favorito de la arquitectura de software, Fuma sigue señalando la POO (programación orientada a objetos) clásica en Java, una elección de una simplicidad casi radical.
“La idea del objeto es muy elegante. Pienso en términos de extender clases”, dijo. “Es un modelo universal que funciona igual en Java, JavaScript y muchos otros lenguajes con los que uno trabaja”.
Fuma Nama se autodenomina un “open sourcerer” en su sitio web. Después de haber aprendido C# desde cero, no sorprende que describa los frameworks modernos de desarrollo web como React.js y Vite como “brillantes y mágicos”. Su experiencia del software está hechizada por un sentido de posibilidad creativa.
“Me siento mal si no he tocado mi editor en todo un día”, dijo Fuma. “Incluso cuando viajo, lo primero que hago al despertarme es abrir mi computadora y abrir mi editor. A veces ni siquiera sé bien qué estoy haciendo, pero simplemente quiero abrir mi editor”.
“Lo que otra persona podría sentir al dibujar, yo lo siento al programar”, dijo Fuma.
El ecosistema open-source
Fuma es muy consciente de que las bibliotecas open-source son la visión y el esfuerzo acumulados de multitud de desarrolladores.
«Es interesante que puedas tener al alcance de la mano todas estas ideas que se diseñaron entre mucha gente y con mucho esfuerzo», dijo Fuma Nama. «Es como sentir la naturaleza y el planeta. Realmente puedes sentir a las personas de todo el mundo».
«Por ejemplo, el Server Component [de React] requirió muchas mentes brillantes. El proceso de RFC hizo que hubiera muchos desarrolladores implicados junto a los miembros del núcleo de React», dijo, en referencia al proceso Request For Comments.
Cuando Fuma empezó a construir lo que acabaría siendo Fumadocs, lo llamó en un principio «Next-docs».
«Pensé que sería divertido crear el framework de documentación formal de Next.js, lo cual era una ambición un poco descabellada», dijo. «Pero era un experimento, justo cuando apareció el Server Component durante la era del App Router, y era un pattern interesante que no había probado. Para mí, el código en sí es como un juguete con el que quiero experimentar».
Más tarde rebautizó su framework como Fumadocs para no entrar en conflicto con la documentación oficial. (El apodo Fuma Nama surge de un juego de palabras desenfadado con el japonés ふわふわ, «fuwa fuwa», que se usa para describir algo ligero y esponjoso. La experiencia de desarrollo ideal, se podría decir).
Fumadocs ha crecido con un profundo apoyo de la comunidad open-source. Las respuestas favoritas de Fuma son las que llegan en forma de comentarios constructivos.
«Me encantan las respuestas que vienen con una pregunta, o cualquier cosa que pueda ayudarme a mejorar el framework», dijo. Fuma todavía cita un issue abierto hace dos años por el desarrollador Anthony Shew. En su solicitud de funcionalidad, Shew intuye que la intención de diseño de Fumadocs se inclina claramente hacia una visión de «menos magia, más componibilidad».
«Fue uno de los primeros en adoptar [Fumadocs] en un proyecto importante», dijo Fuma. «Me dio comentarios valiosos y muy concretos. Entendía de verdad los objetivos del proyecto y le importaban, lo cual me sorprendió».
Desde entonces, Fumadocs ha superado las 13.000 estrellas en GitHub y lo usan empresas como Vercel, Unkey, Orama y nosotros mismos. Durante los últimos tres años, Fuma Nama ha seguido construyendo y manteniendo el framework, invirtiendo cientos de horas al margen de sus estudios y otras obligaciones.
Tras la búsqueda del oficio de Fuma Nama subyace un conjunto de filosofías más profundas sobre los frameworks de desarrollo web y el diseño de software.
Menos abstracción, software menos dogmático
En la sección Philosophy de la documentación de Fumadocs, Fuma define la tesis central: Fumadocs está hecho para ser un framework de documentación que puedes romper.
Con «rompible» se refiere a la capacidad del desarrollador de desarmar y rehacer cualquier pieza del framework. El espíritu de Fumadocs es servir a quienes no solo quieren una documentación que funcione, sino que quieren construir «la documentación perfecta»: adaptada a sus necesidades, preferencias y sentido de la belleza particulares.
«Necesitamos un sistema realmente, realmente componible», dijo. «Un framework lo bastante completo y, a la vez, extremadamente componible». Fumadocs busca dar a los desarrolladores piezas de Lego modulares y comprensibles, que puedan combinar de formas muy distintas para construir sitios de documentación muy distintos.
El enfoque de Fuma parte de un diagnóstico más amplio: los frameworks web modernos están demasiado abstraídos. Resultan «mágicamente» fáciles de usar porque la complejidad queda oculta; pero eso también esconde la lógica subyacente, la mecánica y las concesiones inevitables. Por ejemplo, un desarrollador principiante puede usar la Metadata API de Next.js sin tener idea de cómo funciona la etiqueta meta, o poner lógica en un Server Component sin saber cuánto cuesta ese cómputo.
Un exceso de abstracción impide que los desarrolladores puedan ver, entender y modificar el código de verdad. Por eso su objetivo con Fumadocs es que sea «menos mágico». El framework deja los archivos de rutas en tu repositorio, hace que crees el manejador de solicitud de búsqueda, te permite llamar al cargador de contenido desde tu propio código y puede copiar componentes de interfaz de usuario directamente a tu codebase mediante la CLI.
Fuma define explícitamente el framework como no dogmático. El término «software dogmático» designa a un framework o biblioteca que impone un conjunto de convenciones y guía a los usuarios hacia una única forma «correcta» de construir. (A veces se confunde con el simple hecho de tener una opinión, o se emplea como si fuera algo universalmente positivo). El software dogmático, con sus valores predeterminados rígidos y su camino «correcto» para construir, choca con los objetivos de Fuma: componibilidad, capacidad de romper el sistema y menos abstracción.
Fumadocs es, así, un framework menos mágico y menos dogmático.
Aun así, Fuma reconoce la necesidad de ofrecer a los desarrolladores una usabilidad y una completitud inmediatas. Con ese fin, ha diseñado la biblioteca de interfaz de usuario como una capa más dogmática del framework, con un diseño visual predeterminado sólido. De este modo, los desarrolladores pueden crear de inmediato documentación de aspecto elegante sin perder la capacidad de modificar cada pieza modular. (Lo que significa que podrían sustituirla por completo por su propia interfaz de usuario, si así lo quisieran).
«Lo más difícil de Fumadocs es equilibrar los dos extremos de usuarios», dijo. «Por un lado están los desarrolladores que no quieren hacer ninguna modificación y solo buscan empezar rápido y sin complicaciones. Por otro están los que quieren personalizarlo todo, hasta el punto de que apenas se reconoce la forma original».
Este ejercicio de equilibrio es un reto para la mayoría de autores de frameworks y bibliotecas, y es solo una de las muchas concesiones sobre las que Fuma Nama ha reflexionado a fondo.
Una caja negra y un compilador
Distribuir el código como un package, algo habitual por defecto en una biblioteca, ha sido una decisión muy meditada para Fuma.
«El package es una especie de caja negra para la mayoría de los desarrolladores, a menos que revisen el source code», dice Fuma. «Por supuesto, siempre puedes modificar el código parcheándolo. Pero, una vez que lo metes dentro de un package, en realidad no sabes qué ocurre ahí dentro».
El problema se agrava a escala. «Cuanta más lógica metes en el package, es como meter más código en la caja negra», señala.
El enfoque alternativo, el modelo de shadcn/ui de copiar los componentes directamente en tu codebase, evita el problema de la caja negra. Pero tiene sus propios inconvenientes.
«El coste de mantenimiento siempre recae sobre ti», afirma. «Y cada vez que el framework mejora o incorpora una nueva función, tienes que refactorizar mucho código. En algún momento, deja de tener sentido».
Fuma resuelve este dilema en Fumadocs incorporando vías de escape progresivas. El package sigue siendo el modelo principal, mientras que la CLI (inspirada en shadcn/ui) echa una mano a los desarrolladores que necesitan una personalización más granular. La CLI funciona por componente e incluso puede hilar más fino: permite extraer una sola ranura de un diseño (por ejemplo, solo la tabla de contenidos). La copia del componente pertenece al desarrollador, y la prop slots la vuelve a conectar con la estructura circundante, de modo que las futuras versiones pueden seguir actualizándose desde el package de Fumadocs sin sobrescribirla.
Entre bastidores, Fuma Nama menciona la CLI como una de las piezas más difíciles de construir. Es, en la práctica, un compilador que debe tomar el componente original del package y transformarlo en archivos independientes compatibles con el proyecto y el framework de destino.
«Tienes que transformar un componente que funciona dentro de un package y convertirlo de nuevo en algo separado, aislado en un archivo que pueda descargarse al codebase», explica. «Tuve que aprender todos los frameworks y hacer muchas pruebas para asegurarme de que el AST fuera correcto». (La transformación del Árbol de Sintaxis Abstracta consiste en analizar el archivo fuente del componente para convertirlo en un árbol, reescribir sus rutas de importación para que coincidan con el destino y adaptar la sintaxis).
Con la CLI, las cuatro capas modulares del framework quedan completas: Content, Core, UI y CLI.
Fuma describe Fumadocs como «un conjunto de utilidades y plugins de MDX». Su integración favorita es Story, creada para la documentación de bibliotecas de componentes. Story es un terreno donde Fumadocs realmente brilla, ya que los componentes interactivos no pueden mostrarse solo con Markdown, un factor limitante para los frameworks de documentación menos flexibles.
«Aunque empezara otra vez desde cero, creo que Fumadocs probablemente tendría la misma estructura», dice Fuma. Es un framework que se puede romper de verdad, y que ha sido diseñado meticulosamente para que así sea.
El credo de diseño de Fumadocs
La filosofía de diseño de Fuma para la documentación tiende hacia una experiencia de usuario minimalista, con una atención profunda a cada detalle; su sensibilidad para el diseño visual va de la mano con su convicción sobre la simplicidad en el código.
«Me atrae la abstracción de la forma en el arte del diseño. Intento incorporarla en mis propios diseños para representar algo a partir de figuras geométricas», comentó. «El logotipo de Fumadocs es un círculo que yo llamaría la luna, Luna».
«Dediqué mucho tiempo simplemente a pulir los detalles. El diseño predeterminado ha cambiado muchísimas veces, con iteraciones muy pequeñas en cada versión», señaló.
Fuma Nama cree que una «interfaz de usuario vistosa y llamativa» encaja mejor en una página de inicio, mientras que las páginas de documentación deberían centrarse en el contenido y en una experiencia de lectura sencilla.
El diseño de la tabla de contenidos (TOC) es un ejemplo de un aspecto visual discreto pero profundamente meditado de Fumadocs.
«Me inspiró el deslizador de la documentación de Clerk. Pero quería hacerlo de otra manera, de una forma más bonita», explicó. La mecánica del deslizador es complicada debido al renderizado en el servidor. El servidor dibuja el contorno, pero no puede medir el navegador, así que la parte interactiva debe reconstruirse en el cliente. Funciona trazando la estructura del contorno como una ruta SVG y aplicándola como máscara CSS, con un bloque luminoso que se desliza por detrás para que el resaltado de la «sección activa» recorra la línea.
«Supongo que quizá la gente no lo note», reflexionó Fuma. Pero vale la pena cuidar los pequeños detalles, y está claro que su atención a los matices del diseño visual nace de su preocupación más amplia por la experiencia del desarrollador y del lector.
«Muchas veces no solo estás construyendo la solución, la estás diseñando», afirmó. «Tienes que probar distintos enfoques hasta que funcione de manera equilibrada».
Software perfecto
La próxima iteración de Fumadocs Plus incluirá un manejo más simple, para servir mejor tanto a los principiantes como a la IA. «Menos complejidad es mucho mejor para la IA», explicó Fuma. «Porque, como sabemos, la IA puede alucinar bastante».
Señala que recibe menos issues que antes, probablemente por los agents, que no abren un issue sino que sortean el problema. Se ha vuelto más difícil construir un ciclo de retroalimentación. «Si los agents no reportan errores, no puedo corregirlos», dijo. «Pero sigo trabajando activamente en todos los proyectos y manteniendo los issues al mínimo».
Recibe con gusto las contribuciones de la comunidad open-source. «Si quieres aportar una funcionalidad o cualquier cosa a mis repos, simplemente abre un issue y di que quieres contribuir», dijo. «Estaré encantado de revisarlo».
«Espero que Fumadocs sea el framework de documentación de la web», dijo. «Y quiero seguir convirtiéndolo en el estándar para la interfaz de usuario».
Fuma también está desarrollando otro software open-source, con trabajo activo en tegami, una herramienta para gestionar changelogs y versionado, y fumadb, una API de base de datos para bibliotecas.
«Creo que el open-source crecerá más a medida que más empresas empiecen a reconocer a la comunidad open-source y a devolverle algo», dijo. Señaló que la IA está reconfigurando el ecosistema, reduciendo el costo de mantenimiento de los proyectos y dando más espacio a los mantenedores.
Fuma menciona a Daishi Kato como su inspiración en el open-source, especialmente su framework RSC Waku y su biblioteca de gestión de estado Jotai.
«Waku está realmente infravalorado. La idea clave es que es muy minimalista y componible, y por eso construí Fumadocs y muchos otros proyectos sobre él», dijo. La afinidad filosófica es evidente: el sitio web de Waku describe el framework como «ligero» y con una «experiencia divertida para el desarrollador».
Fuma ha dedicado un tiempo inmenso a sus proyectos open-source, con un esfuerzo minucioso que a menudo pasa desapercibido. Considera que todos sus proyectos son sus tesoros y obras en constante evolución.
«Quiero construir software perfecto», dijo. «Cero issues en mis repositorios, ese es más o menos mi objetivo». Si el software perfecto existe, puede que Fuma Nama sea justamente quien lo construya.