From Legacy to Delight: The Future of Node.js DX

Hola a todos, desde Git Nation y JS Nation asistiendo a JS Nation 2026. Soy Claudio Bonder y hoy voy a hablar sobre De lo legado a lo placentero, el futuro de la experiencia del desarrollador de Node.js. Esta charla está disponible en el código QR a continuación en caso de que quieras tener siempre una copia de las diapositivas o quieras leer el material después. Y también estará disponible en el Portal de JS Nation y el Portal de Git Nation en línea en el futuro.

Soy Claudio Bonder. Soy ingeniero de plataforma en HubSpot, donde mantengo gran parte de toda la plataforma de front end, muchas herramientas internas, por lo que mis clientes son los ingenieros, los especialistas en marketing y todos los que trabajan dentro de HubSpot. También soy uno de los colaboradores principales dentro del proyecto Node.js, donde lidero principalmente nuestros esfuerzos de experiencia del desarrollador e infraestructura. También soy uno de los miembros con derecho a voto dentro de la OpenJS Foundation y la Linux Foundation, donde realizo trabajo de gobernanza diaria dentro del ecosistema de JavaScript. También soy el vicepresidente del Comité de Dirección Técnica del Proyecto Webpack.

En la charla de hoy, vamos a hablar sobre por qué los documentos de Node.js son importantes y cómo funcionan o cómo funcionaban anteriormente con las herramientas antiguas y en qué hemos estado trabajando en los últimos dos años, a saber, dock kit y cómo lo construimos. Uno de los aspectos más destacados de esta charla va a ser la experiencia del desarrollador que estamos tratando de mejorar para los usuarios de Node.js y también la experiencia del usuario para ellos, y también la experiencia del desarrollador para los mantenedores que mantienen Node, cómo desarrollan documentos y cómo las nuevas herramientas mejorarán eso para ellos. Así que sin más preámbulos, ¿por qué importan los documentos de Node.js? Así que probablemente ya hayas leído esta página, incluso si nunca has tocado realmente esta URL. Node.js tiene más de 150 módulos y alrededor de 1500 páginas de referencia y cientos de miles de métodos y clases con los que probablemente hayas tenido que familiarizarte antes.

La fuente de los documentos de API está escrita en el mismo repositorio que Node.js en sí. Está escrita por las personas que desarrollan Node porque, ya sabes, tiene sentido que los colaboradores que están creando esas APIs siempre mantengan esas APIs. Se envía con cada nuevo lanzamiento de Node.js, lo que significa que los cambios en los documentos de API solo pueden hacerse, como, percibidos o vistos cada vez que tenemos un nuevo lanzamiento de Node. Y la mitad del ecosistema de JavaScript realmente lee esas páginas. Nuevamente, incluso si nunca realmente lo tocaste, pero la probabilidad es que hayas abierto Node.js API en algún momento es muy alta. Si no, types Node, que es prácticamente lo que necesitas usar cuando estás usando TypeScript y codificando con TypeScript con cualquier cosa incluso remotamente relacionada con Node.js, mientras se basa y se genera en base a esos documentos de API.

Nuestros tiempos de ejecución competidores o como nuestros compañeros tiempos de ejecución de JavaScript y ecosistema, Bun y Dino, su paridad de tiempo de ejecución y cómo necesitan, por ejemplo, crear una capa de compatibilidad que tienen de Node.js también proviene de nuestros documentos de API. La asistencia de IA, como Copilot, ChatterBot, Cloud, todos ellos se entrenan en esos documentos de API. Y por supuesto, los millones de humanos que están leyendo y trabajando con Node.js, ya sabes, ellos también dependen de esos documentos. Si tenemos algún tipo de error dentro de los documentos o algo mal escrito, hay un ecosistema por qué Bazray se usó. Y en general, necesitarás esperar al próximo lanzamiento para que se haga el parche, lo cual no es ideal. Así que vamos a hablar sobre el O2E aquí.

¿Qué potencia la última década de documentos de API dentro del proyecto Node? Así que básicamente era una herramienta que estaba ligada dentro del ciclo de lanzamiento de seis semanas de Nonstick JS. Ya sabes, CSS seis tardaría mucho tiempo en ser enviado. No había empaquetado, ni servidor y nada realmente que el ecosistema pudiera reutilizar. Estaba completamente atado a Node.js y solo funcionaría con Node.js y codificado para trabajar con el tiempo específico que existía la base de código de Node.js. Estaba prácticamente mantenido junto con muchos regacts y concatenación de cadenas. Así que la forma en que se construyeron todos los documentos de API fue con muchos trucos y código espagueti que intentaremos analizar los documentos de markdown de origen e intentar construir un HTML y una salida JSON de lo que serán los documentos de API en un formato JSON. Pero realmente no tenía ninguna prueba. Realmente no tenía ningún propietario. Y la mantenibilidad era terrible. Así que está un poco atascado por diseño.

Como es un tooling que creció y no fue realmente diseñado. Fue creado por la necesidad de que Node necesitaba tener documentos de API porque ahora se volvió popular desde su lanzamiento y su concepción. Fue más como una ocurrencia tardía. Es una utilidad que se convirtió en un motor por accidente. Está bastante cerrado al exterior. No hay una API pública. No hay una superficie de plugin. Y la única forma en que alguna vez querrás hacer cambios es mediante fork y con una gran advertencia porque, nuevamente, no es realmente algo que estuviera destinado a ser utilizado por cualquier otra cosa. Y uno de los mayores problemas es la falta de documentación del tooling en sí, lo cual es una ironía.

Así que solo una cantidad muy limitada de personas sabía cómo funcionaba y por qué funcionaba de esa manera, lo que hace que cualquier cambio sea muy aterrador porque no podrías realmente validar y no haría que algo más dejara de funcionar dentro de los documentos de API debido a la falta de validación y pruebas. Y las nuevas ideas realmente no tenían dónde vivir. Era bastante difícil hacer cualquier cambio significativo que no fuera como un cambio de CSS o tal vez algún pequeño cambio de tema dentro de la plantilla HTML existente. Agregar nuevas características o cualquier cosa que permita al usuario realmente interactuar con la página, era imposible, que es una de las razones por las que no teníamos medios para proporcionar motores de búsqueda dentro de la página o incluso un mejor sistema de navegación o incluso traducciones dentro de los documentos de API porque era una gran limitación del código en sí.

Así que, ya sabes, los documentos de API son malos para todos los que prácticamente los tocaron. No era malo para los colaboradores porque era una base de código que realmente nadie quería tocar. Porque cambiar una pequeña regex, aunque cuando pruebas una página en código parece array, debido al volumen y tamaño de las páginas de la API de Node doc, era prácticamente imposible para ti verificar manualmente que no hubieras roto accidentalmente algo. Así que fue una experiencia terrible para los colaboradores. Fue terrible para el ecosistema porque todos dependían del output de los documentos de API pero nadie podía realmente depender del tooling detrás de ellos que generaba esos documentos de API. Y finalmente, fue bastante malo para los lectores, pero no voy a mentir, leer esos documentos de API e interactuar con ellos, revisarlos, intentar incluso encontrar clases o métodos específicos que quieres usar, y luego incluso entender cómo funcionan debido al diseño actual de esos documentos de API, era prácticamente imposible.

Así que estoy bastante seguro de que cada desarrollador en esta sala ha fallado como uno, los documentos en sí. Así que también es una página congelada en 2014. La última vez que realmente hicimos algún cambio de diseño significativo fue de hecho en 2014. Y como el sitio web anterior de Node.js fue rediseñado en 2022, fue horrible. Ya sabes, páginas muy largas, difíciles de escanear, muy difícil de entender cuáles son las firmas de los métodos, qué paso cuando llamo a este método, cómo funciona, qué devuelve, cómo encuentro las cosas. La navegación estaba prácticamente anclada por comando F y solo era realmente útil si ya conocías la respuesta.

Incluso la IA tiene dificultades para leer esos documentos de API y a menudo comete errores, sin mencionar las brechas de accesibilidad. Son horribles. Como, esta página no estaba destinada a ser inclusiva, desafortunadamente. Y esta cita ahora representa muy bien el estado de esos documentos de API. Los documentos de Node.js están realmente desordenados. No siguen ni siquiera el diseño de tres columnas de muchos otros sitios de documentación como MDN, React, o incluso Next.js. No es solo la falta de contenido de tutoriales, también es la forma en que se presenta el contenido existente. Y no había forma de arreglar eso con el tooling actual.

Y esta es una opinión y un pensamiento que muchos tienen. Es una voz fuerte y no solo la voz de una minoría. Necesitábamos un cambio. Así que después de dos años de trabajo ininterrumpido de un conjunto bastante impresionante de colaboradores dentro del ecosistema de Node.js, algunos genios, mantenedores dentro de Node.js con los que alguna vez tuve la oportunidad de trabajar, llegamos a Dockit.

Así que Dockit es prácticamente un motor AST genérico que funciona con algunas tecnologías que seleccionamos con el tiempo como Rhodon, Lighting, CSS, SWC, Preact y Piscina. Todas esas tecnologías se mezclan para hacer una generación de pipeline sin problemas. Y también utilizan algunas de las herramientas más modernas, rápidas y confiables que existen por ahí. Y también estamos muy orgullosos de colaborar con los equipos detrás de Rhodon, SWC y Lighting, CSS y Orama para realmente hacer que esto funcione para Node.

Porque una de las limitaciones interesantes que tenemos es que Node necesita, y esos documentos de API necesitan poder funcionar y ser generados en prácticamente todos los entornos, arquitecturas y plataformas en las que Node se ejecuta. Así que este es un caso de estudio muy interesante que compartiré después en la lectura de la reunión después de la charla. Pero con los dos años de trabajo, nos enfocamos mucho en la experiencia del usuario.

Podemos ver lado a lado lo que teníamos a la izquierda y lo que tenemos a la derecha. Inmediatamente es más fácil, al menos para mí, saber cuál es la firma de tipo de este método, cuáles son las opciones reales que pasas y qué devuelve.

Es fácil de leer, fácil de saber cómo funciona, es fácil de navegar. Y el rediseño es siempre completamente accesible y adaptable, y tiene muchas travesuras que creo que a mucha gente le van a encantar. Así que tuvimos un momento difícil porque somos perfeccionistas, al menos en la experiencia del usuario, y queríamos desarrollar la experiencia para los usuarios de Node.js para que sea lo mejor posible. Así que tuvimos prácticamente un año, como 11 meses de solo iterar sobre la retroalimentación proporcionada por otras personas.

Así que en Docket, el proceso es muy fácil. Docket soporta tanto Markdown como JSDoc y TSDoc como fuentes para la generación de documentación de API, por lo que puedes tener páginas regulares de Markdown o páginas de API Markdown. Transformaremos todo esto en AST, que recogerá todos los metadatos, y luego transformará todos los metadatos en AST en GSX.

Y finalmente, tendrás el sitio web final con tus componentes de React y tus temas y diseños que puedes personalizar como quieras. Docket también es modular, lo que significa que tenemos, después de transformar la fuente en un AST, es consumido por varios, lo que llamamos, generadores, o como plugins, para funcionar correctamente. Así que ya tenemos más de 10 generadores diferentes para probar, por ejemplo, generando salida para LLMs, especificación JSON, y muchos otros que permiten, prácticamente, si quieres crear un plugin, consumir esos AST de origen y transformarlo en lo que sea.

También creamos una especificación, que es prácticamente una gramática formal, un conjunto estricto de common mark que creemos que funcionará muy bien con cualquier tipo de documentación de API. Para dejarlo muy claro, Docket no es como el futuro solo del ajuste de API de Node.js. También es algo que estamos lanzando a la comunidad, como una especie de DocuSource que permite a la comunidad generar también su propia documentación de API.

Y voy a hablar un poco más sobre eso en las siguientes diapositivas. Como mencioné, creamos una especificación que puedes leer desde este código QR, y fue cuidadosamente elaborada por Aviv Keller, uno de nuestros colaboradores. Y como mencioné, es un superconjunto de common mark, y tiene prácticamente todo lo que creemos que una especificación necesita tener para crear documentación de API impresionante, ya sea algo que el usuario esté leyendo al final, o simplemente como el markdown fuente.

Y llamo a todos los que están viendo esta charla si están interesados en esto. Creo que es una especificación bastante interesante para leer. Así que, cómo lo construimos.