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

Hola a todos de Git Nation y JS Nation que asisten a JS Nation 2026. Soy Claudio Bunder, y hoy voy a hablar sobre De lo Legacy a lo Delight, el Futuro de la Experiencia del Desarrollador de NeoJS. Esta charla está disponible en el código QR a continuación en caso de que desees tener 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 Bunder. Soy ingeniero de plataforma en HubSpot, donde mantengo gran parte de nuestra plataforma de front-end, gran parte de nuestras herramientas internas. Así 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 principalmente lidero 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 NeoJS son importantes y cómo funcionan o cómo funcionaban anteriormente con las herramientas antiguas, en lo que hemos estado trabajando en los últimos años, a saber, DocKit, 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 leíste esta página, incluso si nunca tocaste esta URL. Node.js tiene más de 150 módulos, alrededor de 1500 páginas de referencia, y cientos de miles de métodos y clases con los que probablemente tuviste que familiarizarte antes. La fuente de los documentos de la API está escrita en mockdown en el mismo repositorio que Node.js mismo. Está escrita por las personas que escriben Node, porque tiene sentido que los colaboradores que están creando esas APIs también mantengan esas APIs. Se envía con cada nuevo lanzamiento de Node.js, lo que significa que los cambios en los documentos de la API solo pueden hacerse, como, percibirse o verse 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 de que hayas abierto los documentos de la API de Node.js en algún momento es muy alta. Si no, Type's 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 que se basa y se genera en base a esos documentos de la 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 capas de compatibilidad que tienen de Node.js también provienen de nuestros documentos de la API. Los asistentes de IA como Copilot, Chatterbot, Cloud, todos ellos se entrenan en esos documentos de la API. Y por supuesto, los millones de humanos que están leyendo y trabajando con Node.js, tú sabes, también dependen de esos documentos. Si tenemos algún tipo de error dentro de los documentos o algo mal escrito, hay un radio de explosión en todo el ecosistema. Y en general, necesitarás esperar al próximo lanzamiento para que se realice el parche, lo cual no es ideal.

Ahora vamos a hablar sobre O2E aquí. Lo que impulsó la última década de documentos de la API en el proyecto Node. Así que prácticamente era una herramienta que estaba ligada dentro del ciclo de grandes lanzamientos de JSS6. Sabes, CSS6 tardaría mucho en ser enviado. No había empaquetado, no había ahorrador, y nada realmente que el ecosistema pudiera reutilizar. Estaba completamente ligado a Node.js y solo funcionaría con Node.js y codificado para trabajar con un tiempo específico en la base de código de Node.js existía.

Estaba prácticamente mantenido junto con muchos remiendos y concatenación de cadenas. Así que la forma en que se construyeron los documentos de la API fue con muchos hacks y código espagueti. Intentábamos analizar los documentos markdown fuente y tratar de construir una salida HTML y JSON de lo que serían los documentos de la 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 si fuera una herramienta que creció y no realmente diseñada. Fue creada por la necesidad de que Node necesitaba tener documentos de API porque Node se hizo popular desde su lanzamiento y su concepción. Fue más como una ocurrencia tardía. Es una agilidad que se convirtió en un motor por accidente. Está prácticamente cerrado al exterior, no hay API pública, no hay superficie de conexión. Y la única forma en que alguna vez querrías hacer algún cambio es un fork y una gran advertencia porque de nuevo, no es realmente algo que estuviera destinado a ser usado por cualquier otra cosa. Y uno de los mayores problemas es la falta de documentación de la propia herramienta, lo cual es una ironía. Así que solo una cantidad muy limitada de personas incluso 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 validarlo, no haría que algo más dejara de funcionar dentro de los documentos de la 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. No era 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 permitiera 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 la API porque era una gran limitación del propio código.

Así que ya sabes, no tener documentos de API es malo para todos los que prácticamente lo tocarían. No era malo para los colaboradores porque era una base de código enredada que realmente nadie quería tocar porque cambiar un tiempo regacts. Aunque cuando pruebas una página y el código se ve bien, debido al volumen y tamaño de las páginas de la API de Node, era prácticamente imposible para ti verificar manualmente que no habías roto accidentalmente algo. Así que fue una experiencia horrible para los colaboradores. Fue horrible para el ecosistema porque todos dependían de la salida de los documentos de la API, pero nadie podía realmente depender de la herramienta detrás de ella que generaba esos documentos de la API. Y finalmente, fue bastante malo para los lectores.

Pero no voy a mentir, leer esos documentos de la 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 la API, era prácticamente imposible. Así que estoy bastante seguro de que cada desarrollador en esta sala ha fallado como uno, los propios documentos. Así que también está 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. Sabes, páginas muy largas, difíciles de escanear, sabes, muy difícil de entender cuáles son los métodos de firma? ¿Qué tan alto realmente, qué debo pasar cuando llamo a este método? ¿Cómo funciona? ¿Qué devuelve? ¿Cómo encuentro las cosas? La navegación estaba prácticamente anclada por común AF. Y solo era muy, muy útil si ya sabías la respuesta. Incluso la IA tiene dificultades para leer estos documentos de la API y a menudo comete errores, sin mencionar las brechas de accesibilidad. Son horribles. Como si esta página no estuviera destinada a ser inclusiva, desafortunadamente. Y esta cita ahora representa muy bien el estado de esos documentos de la API. Que los documentos de Node.js son realmente un desastre. No siguen ni siquiera el diseño de tres columnas de muchos otros sitios de documentación como MGM, 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 las herramientas actuales. Y esta es una opinión y un pensamiento que muchos tienen. Es una voz fuerte y no solo una voz de minoría. Necesitábamos tener un cambio.

Así que después de dos años de trabajo ininterrumpido de un conjunto de colaboradores pre-asombrosos dentro del ecosistema de Node.js, algunos enfriadores, 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 RhoDone, Lighting, CSS, SWC, Preact y Ficina. Todas esas tecnologías se mezclan para hacer una canalización de generación 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 RhoDone, SWC, Lighting, CSS y Orama para realmente hacer que esto funcione para Node. Una de las limitaciones interesantes que tenemos es que Node necesita y esos documentos de la API necesitan poder trabajar y ser generados en prácticamente todos los entornos y arquitecturas y plataformas en las que Node se ejecuta. Así que este es un caso de estudio muy interesante que compartiré después en el meet and greet después de la charla. Pero con los dos años de trabajo, nos enfocamos mucho en la experiencia del usuario. Puedes ver lado a lado lo que teníamos a la izquierda y lo que tenemos a la derecha. 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.

El rediseño es siempre completamente accesible y responsivo y tiene muchas travesuras que creo que a mucha gente le van a encantar. Tuvimos un momento difícil porque somos perfeccionistas, al menos en la experiencia del usuario, y queríamos que la experiencia del desarrollador para los usuarios de Node.js fuera lo mejor posible. Así que tuvimos prácticamente un año, como 11 meses, solo iterando sobre la retroalimentación proporcionada por otras personas.

Con Dockit, el proceso es muy fácil. Admite tanto Markdown como JS Doc y TS Doc como fuente para la generación de Documentos de API. Puedes tener páginas de markdown regulares o páginas de markdown de API, que transformarán todo esto en AST, que recogerá todos los metadatos, y luego transformará todos los metadatos y AST en JSX. Y luego finalmente, tienes el sitio web final con tus componentes React y tus temas y diseños que puedes personalizar como quieras.

Dockit también es modular, lo que significa que después de transformar la fuente en un AST, es consumido por varios generadores diferentes, como plugins para funcionar correctamente. Así que ya tenemos más de 10 generadores diferentes para probar. Generadores que están generando salida para LLMs y especificación JSON y muchas órdenes que permiten prácticamente si quieres crear un plugin y consumir esos AST de fuente y transformarlo en lo que sea. También creamos una especificación, que es prácticamente una gramática formal, ya sabes, un superconjunto estricto de common mark que creemos funcionará muy bien con cualquier tipo de documentos de API.

Para dejarlo muy claro, Dockit 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 también generar 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. Fue elaborada a mano por Aviv Keller, uno de nuestros colaboradores. Y eso es, como mencioné, un superconjunto de common mark y tiene prácticamente todo lo que creemos que la especificación debe tener para crear una documentación de API impresionante, ya sea como, sabes, algo que el usuario está leyendo al final o simplemente como el markdown fuente. Llamo a todos los que están viendo esta charla, si están interesados en esto, creo que es una especificación bastante genial para leer.

Así que cómo lo construimos. Como mencioné, todas las herramientas que usamos, Regaxis, prácticamente para identificar la estructura del documento. Ahora mismo estamos usando AST, impulsado por el Ecosistema Unificado para prácticamente leer markdown, JS doc, TS doc, y poder analizar todos los diferentes elementos y jeroglíficos y encabezados y cualquier texto que esté dentro del markdown para generar AST que podrá separar qué es un encabezado, qué es una definición de tipo, qué son slugs, qué es como una etiqueta de inestabilidad. Como si esta clase específica está duplicada o estable o en desarrollo, también desde los metadatos YAML, referencias cruzadas, como poder mover información de MDN, etc. Es un motor muy genial que tomó mucho tiempo y mucho esfuerzo hacer porque queremos asegurarnos de que se mantenga eficiente y pueda entender prácticamente tan abstracto como sea posible ese árbol de sintaxis y seguir la especificación que hemos hecho. El código está muy bien documentado y nuevamente, siempre te animo a que mires el código fuente de Dockit si estás interesado.

La forma en que también funciona es con un sistema generador, piensa en el sistema de plugins, los generadores son lo que generan, toman una entrada y generan una salida, y dentro del pipeline, por ejemplo, para que puedas ver cuáles son ahora mismo las páginas HTML, tienes al menos cinco pasos desde el proceso inicial de ASU, recopilando los metadatos, solo para mí en JSX, luego pasando a través de un React y React con los componentes para luego el HTML final que también es 100% del lado del servidor. Por ejemplo, en esta pestaña tenías cinco generadores diferentes. El sistema generador te permite prácticamente engancharte a la fuente y prácticamente crear cualquier cosa a partir de ella, generar cualquier cosa a partir de ella. El lado técnico genial detrás de esto es la forma en que está diseñado es que los diferentes generadores, aunque son secuenciales, imagina que web es el resultado que viste en las líneas anteriores de la página rediseñada y ASC es la fuente y la forma en que están diseñados es que prácticamente trabajan en un proceso de fragmentación de rendimiento que mientras la primera parte anterior del pipeline tenga algo ya listo, lo enviará al siguiente generador, lo que te permite trabajar en un sistema basado en paralelo y también fragmentar la información. Esto es muy crítico porque cuanto más grande sea tu documentación de API, más páginas de markdown tengas, más fuente tengas, más grande será tu AST y más querrás beneficiarte del multihilo, la fragmentación y todas las increíbles características de paralelismo de Node.js. Así que Dockit irónicamente utiliza las mejores características que tienes en Node.js para crear documentación de API de Node. Y como mencioné, esto no es solo para Node, la especificación está abierta y ahora mismo ya estamos usando Dockit como primeros adoptantes dentro de Webpack para generar la próxima generación de documentación de API de Webpack. Tenemos un proyecto dentro de Google Surmerge Code que tiene como objetivo también tener estudiantes trabajando en él y mejorando Dockit y también lo estamos usando en diferentes repositorios dentro de Node, no solo más con la documentación de API, sino también con los materiales de aprendizaje que tenemos en node.js.org slash learn. Y lo genial es que Dockit se está usando ahora mismo dentro de node.js.org slash API.