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

Hi there, everyone from Git Nation and JS Nation attending JS Nation 2026. I'm Claudio Bonder and today I'm going to talk about From Legacy to Delight, the future of Node.js developer experience. This talk is available on the QR code below in case that you want to always 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 am Claudio Bonder. I'm a platform engineer at HubSpot, where I maintain a lot of all front-end platform, a lot of internal tooling, so my customers are the engineers, the marketers, and everyone that works within HubSpot. I'm also one of the core collaborators within the Node.js project, where I lead mostly 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 Node.js' docs matter and how they work or how they worked previously with the old tooling and what we have been working on in the last two years, namely dock kit and how we build 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've probably already read this page, even if you've never actually touched this URL. Node.js has more than 150 modules and 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 the same repository as Node.js itself. It is authored by the people writing Node because, you know, it makes sense for the contributors that are creating those APIs to always 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 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 to some point is very high. If not, types 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 layer that they have from Node.js also come from our API docs. AI assistance, 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 why Bazray used. And in general, you will need to wait for the next release for the patch to be done, which is not ideal. So we're going to talk about the O2E here.

What power for the last decade of API docs within the Node project? So pretty much it was a tool that was tied within the Nonstick JS six-week release cycle. You know, CSS six would take a long time to get shipped. There was no packaging, no server and nothing really that the ecosystem could reuse. It was completely tied to Node.js and would only work with Node.js and hard-coded to work with the specific time that the codebase of Node.js existed. It was pretty much held together with a lot of regacts and string concatenation. So the way all the API docs were built was with a lot of hacks and spaghetti code that we'll 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 now it became popular since its release and its conception. It was more like an afterthought. It's an utility that became an engine by accident. It's pretty much closed to the outside. There's no public API. There's no plugin surface. And the only way that you ever want to make any changes is by fork and by 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 and 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 that 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.

API docs are bad for everyone who pretty much touched it. It wasn't bad for contributors because it was a table of code base that really nobody wanted to touch. Because changing one tiny regex, although when you test one page in code look array, because of the sheer volume and size of the node doc API pages, it was pretty much impossible for you to verify manually that you wouldn't have accidentally broken something. So it was an awful experience for the contributors. It was awful for the ecosystem because everyone depended on the output of the API docs but nobody could actually depend on the tooling behind it that generated those API docs. And finally, it was pretty much bad for the readers, 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, very hard to understand what are the signature methods, what I pass when I'm calling this method, how it works, what it returns, how I find the things. Navigation was pretty much anchored by command F and it was only really useful if you already knew the answer.

Even AI struggle reading those 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. The Node.js docs are really messed. They do not follow even the three-column design of many other doc sites like MDN, 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.

After two years of nonstop work from a pretty 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 a generic AST engine that works with a few technologies that we selected over time like Rhodon, Lighting, CSS, SWC, Preact, and Piscina. 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.

Dockit is a generic AST engine that integrates technologies like Rhodon, Lighting, CSS, SWC, Preact, and Piscina to create a seamless generation pipeline. Collaboration with teams behind Rhodon, SWC, and Lighting, CSS, and Orama was essential for compatibility across various environments and platforms that Node runs on. The focus on user experience led to a redesign that improved readability, navigation, and accessibility, with attention to detail for Node.js users.

The process in Dockit supports Markdown, JSDoc, and TSDoc as sources for API documentation generation. Transformation into AST and GSX allows customization of React components and themes. With a modular structure, multiple generators ensure correct transformation of source AST into various outputs, including plugins for different specifications and APIs.

Dockit's specification, a common mark grammar, offers a comprehensive guide for creating exceptional API documentation. This tool is not limited to Node.js but is released to the community to generate their own API docs. The emphasis on perfection in user experience and collaboration with contributors highlights the dedication to providing high-quality documentation accessible to all users.

It's easy to read, easy to know how it works, easy to navigate. The redesign is accessible and responsive, offering features that many will appreciate. The focus on perfection in user experience for Node.js users drove a year-long iterative process based on feedback. Dockit simplifies the documentation process by supporting Markdown, JSDoc, and TSDoc sources for API doc generation.

Transformation from Markdown and other sources into AST and GSX enables customization of React components and themes. The modular structure of Dockit involves multiple generators to ensure accurate transformation into various outputs, including plugins for different specifications and APIs. The tool offers a common mark grammar specification for creating exceptional API documentation, emphasizing collaboration and high-quality documentation accessible to all users.

The AST engine in Dockit, powered by the Unified Ecosystem, reads and parses different elements in documents for metadata extraction. The generator system, akin to a plugin system, facilitates the transformation of input into output through a pipeline of steps. The codebase is well-documented, encouraging users to explore the source code, while the generator system allows for the creation of diverse outputs from the source, enhancing flexibility and customization.

We also created a specification, which is pretty much a formal grammar, a strict set of common mark that we believe will work well with any API docs. Docket is not just for Node.js API tuning but a community tool for generating API docs. The specification, a super set of common mark, includes elements essential for creating exceptional API docs and encourages community engagement.

The tool utilizes AST powered by the Unified Ecosystem to read and parse various elements in markdown, JS doc, and TS doc. The AST engine extracts metadata, type definitions, slugs, and YAML, supporting cross-references and different labels. The generator system, like a plugin system, processes input through multiple stages, ensuring performance and adherence to the specification.

Dockit's generator system operates sequentially yet in a parallel-based system, optimizing multi-threading and chunking for large API docs. The tool leverages Node.js features for creating API docs beyond Node, used by early adopters like Webpack. Dockit's future vision includes being a versatile and expertly crafted API doc engine accessible to all users with ease of generation.