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

Hey there, everyone from Git Nation and JS Nation attending JS Nation 2026. I'm Claudio Bunder, and today I'm going to talk about From Legacy to Delight, the Future of NeoJS Developer Experience. This talk is available on the QR code below in case that you want to have a copy of the slides or want to read the material afterwards, and it will also be available on JS Nation portal and Git Nation portal online in the future. I'm Claudio Bunder. I'm a platform engineer at HubSpot, where I maintain a lot of our front-end platform, a lot of our internal tooling. So my customers are the engineers, the marketers, and everyone that works within HubSpot. I am also one of the core collaborators within the Node.js project, where I mostly need our developer experience and infrastructure efforts. I'm also one of the voting members within the OpenJS Foundation and the Linux Foundation, where I do day-to-day governance work within the JavaScript ecosystem. I'm also the vice chair of the Technical Steering Committee of the Webpack project.

On today's talk, we're going to talk about why NeoJS's docs matter and how they work or how they worked previously with the old tooling, what we have been working in the last few years, namely DocKit, and how we built it. One of the key highlights of this talk is going to be the developer experience that we're trying to improve for Node.js users, and also the user experience for them, and also the developer experience for the maintainers maintaining Node, how they develop docs, and how the new tooling will improve that for them. So without further ado, why Node.js docs matter? So you probably already read this page, even if you never actually touched this URL. Node.js has more than 150 modules, around 1500 reference pages, and hundreds of thousands of methods and classes that you probably had to get familiar with before. The source of the API docs are written in mockdown in the same repository as Node.js itself. It is authored by the people writing Node, because it makes sense for the contributors that are creating those APIs to also maintain those APIs. It gets shipped with every new release of Node.js, which means that changes in the API docs can only be done, like, perceived or seen every time that we have a new release of Node. And half of the JavaScript ecosystem actually reads those pages, again, even if you never actually touched it. But the likelihood is that you opened Node.js API docs at some point is very high. If not, Type's Node, which is pretty much what you need to use when you're using TypeScript and coding with TypeScript, with anything even closely related to Node.js, while it relies and gets generated based on those API docs. Our competitor runtimes, or like our fellow JavaScript runtimes and ecosystem, Bun and Dino, their runtime parity and how they need to, for example, create a compatibility layers that they have from Node.js also come from our API docs. AI assistants such as Copilot, Chatterbot, Cloud, all of them get trained on those API docs. And of course, the millions of humans that are reading and working with Node.js, you know, they also rely on those docs. If we have any sort of bug within the docs or anything poorly written, there's an ecosystem wide blast radius. And in general, you will need to wait for the next release for the patch to be done, which is not ideal.

Now we're going to talk about O2E here. What powered for the last decade of API docs in the Node project. So pretty much it was a tool that was tied within the JSS6 big release cycle. CSS6 would take a long time to get shipped. There was no packaging, no saver, and nothing really that the ecosystem could reuse. It was completely tied to Node.js and would only work with Node.js and Harp coded to work with a specific time to the code base of Node.js existed.

It was pretty much held together with a lot of regags and string concatenation. So the way how the API docs were built was with a lot of hacks and spaghetti code. We would try to analyze the source markdown docs and try to build an HTML and a JSON output of what will be the API docs in a JSON format. But it didn't really have any tests, it didn't really have any owner and maintainability was awful. So it's kind of stuck by design, like it's a tooling that was grown and not really designed. It was created by the need that Node needed to have API docs because Node became popular since its release and its conception. It was more like an afterthought. It's an agility that became an engine by accident. It's pretty much closed to the outside, there's no public API, there's no plugging some surface. And the only way that you ever want to make any changes is a fork and a huge caveat because again, it's not really something that was meant to be used by anything else. And one of the biggest problems is the lack of documentation of the tooling itself, which is an irony. So only a very handful amount of people even knew how it worked and why it worked in that way, which makes any change very scary. Because you wouldn't be able to actually validate it, it would not make something else stop working within the API docs due to the lack of validation and testing. And new ideas had really nowhere to live. It was pretty hard to make any significant change. It was not like a CSS change or maybe some small theme change within the existing HTML template, adding new features or anything that allows the user to actually interact with the page. It was impossible, which is one of the reasons why we didn't have any means to provide search engines within the page or even a better navigation system or even translations within the API docs because it was a huge limitation of the code itself.

Now we're going to talk about O2E here. What powered for the last decade of API docs in the Node project. So pretty much it was a tool that was tied within the JSS6 big release cycle. CSS6 would take a long time to get shipped. There was no packaging, no saver, and nothing really that the ecosystem could reuse. It was completely tied to Node.js and would only work with Node.js and Harp coded to work with a specific time to the code base of Node.js existed.

But I'm not going to lie, reading those API docs and interacting with them, going over them, trying to even find specific classes or methods that you want to use, and then even understanding how they work because of the current design of those API docs, it was pretty much impossible. So I'm pretty sure that every developer in this room has failed as one, the docs themselves. So it is also page frozen in 2014. The last time that we really made any significant design change was indeed in 2014. And as the previous Node.js website got redesigned in 2022. It was awful. You know, very long pages, hard to scan, you know, very hard to understand what are the signature methods? How high actually, what should I pass when I'm calling this method? How it works? What are returns? How I find the things? Navigation was pretty much anchored by common AF. And it was only very, very useful if you already knew the answer. Even AI struggle reading these API docs and often make mistakes, not to mention the accessibility gaps. They're awful. Like this page was not meant to be inclusive, unfortunately. And this quote very well, now represents the state of those API docs. That Node.js docs are really mass. They do not follow even the three column design of many other doc sites like MGM, React or even Next.js. It's not only the lack of content of tutorials. It's also the way the existing content is presented. And there was no way to fix that with the current tooling. And this is an opinion and a thought that many have. It is a loud voice and not just a voice of minority. We needed to have change.

So after two years of nonstop work from pre-awesome set of contributors within the Node.js ecosystem, some coolers, maintainers within Node.js that I ever had a chance to work with, we came up with Dockit. So Dockit is pretty much generic AST engine that works with a few technologies that we selected over time, like RhoDone, Lighting, CSS, SWC, Preact and Ficina. All those technologies, they mix together in order to make a seamless generation pipeline. And they also use some of the most modern and fastest and most reliable tools that exist out there. And we're also very proud to collaborate with the teams behind RhoDone, SWC, Lighting, CSS and Orama to actually make this work for Node. One of the interesting limitations that we have is that Node needs and those API docs need to be able to work and be generated in pretty much all the environments and architectures and platforms that Node runs. This is a very interesting case study that I will share afterwards and meet and greet after the talk. But with the two years of work, we focused a lot on the user experience. You can see side by side what we had in the left and what we have on the right. It is easier, at least for me, to know what is the type signature of this method? What are the actual options that you pass and what returns? It's easy to read, easy to know how it works, it's easy to navigate.

The redesign is always completely accessible and responsive and has a lot of shenanigans that I think a lot of people are going to love. We had a hard time because we are perfectionist, at least in the user experience, and we wanted the developer experience for Node.js users to be the best as possible. So we had pretty much one year, just like 11 months, just iterating on feedback provided by other people.

With Dockit, the process is very easy. It supports both Markdown and JS Doc and TS Doc as a source for generation to API Docs. You can have regular markdown pages or API markdown pages, which will transform all of this into AST, which would collect all the metadata, and then it would transform all the metadata and AST into JSX. Dockit is also modular, which means that after we transform the source into an AST, it is consumed by several different generators, like plugins in order to work correctly.

We already have more than 10 different generators to test. Generators that are generating output for LLMs and JSON specification and many others that allow pretty much if you want to create a plugin and to consume those source AST and transform it to whatever. Dockit is not just the future of Node.js API tuning; it is also something we are releasing to the community as a sort of DocuSource that allows the community to generate their own API docs. The tools used, such as Regaxis, help identify the document structure, while the AST, powered by the Unified Ecosystem, reads markdown, JS doc, TS doc, and parses all elements efficiently.

To make it very clear, Dockit is not like the future of just Node.js API tuning. It is also something we are releasing to the community as like a sort of DocuSource that allows the community to also generate their own API docs. And I'm going to talk a little bit more about that in the following slides. As I mentioned, we created a specification which you can read from this QR code. It was like handfully crafted by Aviv Keller, one of our contributors. And that is, as I mentioned, is a super set of common mark and has pretty much everything that we believe that specification is to have to create awesome API docs, be them like, you know, something that the user is reading in the end or just like the source markdown. I call everyone that is watching this talk, if you're interested in this, I think it's pretty cool specification to read.

So how we built it. So as I mentioned, all the tools we used, Regaxis, pretty much to identify the structure of the document. Right now we're using AST, powered by the Unified Ecosystem to pretty much read markdown, JS doc, TS doc, and be able to parse all the different elements and hieroglyphics and headings and whatever text is within the markdown to generate AST that will be able to separate what is a heading, what is a type definition, what are slugs, what is like an instability label. Like if this specific class is duplicated or stable or in the development, also from the YAML metadata, cross references, like being able to move information from MDN, etc. It is a very cool engine that took a lot of time and a lot of effort to make because we want to ensure that it stays performant and it can pretty much understand as abstract as possible that syntax tree and follow the specification that we've done. The code is very well documented and again, I always encourage you to look at the source code of Docket if you're interested.

The way how it also works is with a generator system, think of the plugin system, the generators are what generate, take an input and generate an output, and within the pipeline, for example, in order for you to see what are right now the HTML pages, you have at least five steps from the initial ASU process, collecting the metadata, just for me into JSX, then going through a react and react with the components to then the final HTML that is 100% server side also. For example, in this tab you had five different generators. The generator system allows you to pretty much hook into the source and pretty much create anything off from it, generate anything out from it. The cool technical side behind it is the way how it is designed is that the different generators, even though they're sequential, imagine that web is the result that you saw on the previous lines of the redesign page and ASC is the source and the way how they're designed is that they pretty much work in a yielding chunking process that as long as the first previous part of the pipeline has anything already ready, it will forward to the next generator, which allows you to work in a parallel based system and also chunk the information. This is very critical because the larger your API docs are, the more markdown pages you have, the more source you have, the larger your AST is going to be and the more you want to benefit from multithreading, chunking and all the amazing parallelism features from node.js. So Dockit unironically uses the best features that you have in node.js to create node API docs. And as I mentioned, this is not just for node, the specification is open and right now we are already using Dockit as early adopters within Webpack to generate the next generation version of Webpack API docs. We have a project within Google Surmerge Code that aims to also have students working on it and improving Dockit and we are also using it across different repositories within node, not just anymore with the API docs, but also the learn materials that we have on node.js.org slash learn. And cool thing is that Dockit is being used right now within node.js.org slash API.