Taylor Fang
Fumadocs
We’re excited to announce our first grantee project: Fumadocs, created by Fuma Nama.
Fumadocs is a beautiful and flexible React documentation framework. The framework has four modular layers: Core, Content, UI, and CLI. The architecture and visual design both flow from the core philosophical tenets of composability and simplicity. Each library is a set of “building blocks” which expose how they work, giving developers the ability to modify and create docs exactly the way they want. The visual design integrates elegant, performant components with minute attention to detail. It’s a blazing-fast reader experience for humans and LLMs alike.
Fumadocs is used by Vercel Turborepo, shadcn/ui, BetterAuth, Unkey, and many others. It’s a testament to Fumadocs’ composability that each site looks vastly different. And of course, General Translation uses Fumadocs for our own documentation!
Fuma Nama, the creator of Fumadocs, has thought deeply about developer experience. Inordinate consideration has gone into every layer and detail of the framework: from scaffolding content for readability, to reducing abstraction, to balancing maintenance with customizability.
We caught up with Fuma Nama for his first-ever interview, covering over three years of developing Fumadocs and many more years working in open-source development. (Did you know he just completed high school last year?)
Below, we cover how Fuma Nama learned to code from looking at code files, his take on “opinionated software,” why his libraries take a “less-magic” approach, why open-source is inherently global, and his philosophy on docs reader experience — with easter eggs along the way, like where his moniker comes from and how the Fumadocs logo is inspired by the moon.
The vibrant world of the computer
Fuma Nama grew up in Hong Kong. His family bought a computer when he was 6 years old. He writes of wandering the World Wide Web as a child, where he first experienced the “vibrant world of the computer.” His sense of software is enchanted and playful. In primary school, he patched together a Unity sandbox game so the player could switch between cars and planes in different landscapes: a desert, moon, destroyed city, mountain, and forest.
The notion of “software as a concept” came later to Fuma. Instead, he learned to code through modding videogames and reverse engineering. He describes picking up C# by looking at code, changing it, and then watching what changed in the game.
“It’s kind of crazy. I learned to code from files. Like I would see a huge pile of JavaScript and read that,” he said. “I didn’t look at any kind of documentation, just the code itself.”
By going directly to “the primary source” (albeit accidentally), Fuma came to understand the bare bones cognitive principles at a deep level. He picked up the mental concepts behind a framework, rather than labels attached to behaviors. When asked about his favorite aspect of software architecture, Fuma still points to old-school OOP (object-oriented programming) in Java, a choice that is almost radically simple.
“The idea of the object is very elegant. I think in terms of extending classes,” he said. “It’s a universal model which works the same between Java, JavaScript, and many other languages you touch.”
Fuma Nama calls himself an “open sourcerer” on his website. After learning C# from scratch, it’s no wonder he describes modern web dev frameworks like React.js and Vite as “shining and magical.” His experience of software is bewitched by a sense of creative possibility.
“I feel unhappy if I haven’t touched my editor for a whole day,” said Fuma. “Even when I travel, the first thing I do when I wake up is open my computer and open my editor. Sometimes I don’t actually know what I’m doing, but I just want to open my editor.”
“What someone else might feel in drawing, I feel in coding,” said Fuma.
The open-source ecosystem
Fuma is keenly aware of open-source libraries as the accumulated vision and efforts of manifold developers.
“It’s interesting that you can put your hands on all of these ideas that were designed with a lot of people and a lot of effort,” said Fuma Nama. “It’s like feeling nature and the globe. You can actually feel the people from around the globe.”
“For example, the [React] Server Component took many brilliant minds. The RFC process meant there were a lot of developers involved along with the core members of React,” he said, referencing the Request For Comments process.
When Fuma started building what would become Fumadocs, he originally called it “Next-docs.”
“I thought it would be kind of fun to make the formal Next.js documentation framework, which was kind of a crazy ambition,” he said. “But it was an experiment, right when the Server Component first came out during the App Router era, and it was an interesting pattern I hadn’t tried. For me, the code itself is like a toy that I want to try.”
He later renamed his framework to Fumadocs to not conflict with the official documentation. (The moniker Fuma Nama comes from whimsical wordplay on the Japanese ふわふわ, “fuwa fuwa,” used to describe something that is light and fluffy. The ideal developer experience, one might say.)
Fumadocs has grown with deep support from the open-source community. Fuma’s favorite responses come in the form of constructive feedback.
“I love responses with a question, or anything that can help me to improve the framework,” he said. Fuma still references an issue opened by developer Anthony Shew two years ago. In his feature request, Shew discerns that the Fumadocs design intent leans heavily into a “less magic, more composability” vision.
“He was one of the first to adopt [Fumadocs] on a major project,” said Fuma. “He gave me valuable feedback that was really concrete. He actually understood and cared about the goals of the project, which was surprising to me.”
Fumadocs has since grown to over 13,000 stars on GitHub, and is used by companies like Vercel, Unkey, Orama, and yours truly. Over the past three years, Fuma Nama has continued building and maintaining the framework, investing hundreds of hours on top of his schoolwork and other obligations.
Beneath Fuma Nama’s pursuit of craft is a set of deeper philosophies on web development frameworks and software design.
Less abstraction, less opinionated software
In the Philosophy section of the Fumadocs documentation, Fuma defines the core thesis: Fumadocs is built to be a docs framework you can break.
By “breakable,” he refers to the ability for a developer to take apart and reshape any piece of the framework. The spirit of Fumadocs is to serve those who don’t just want docs that work but who want to build “the perfect docs”: tailored to their unique needs, preferences, and sense of beauty.
“We need a really, really composable system,” he said. “A framework that is complete enough while also being extremely composable.” Fumadocs aims to give developers modular and understandable Legos, which they can use in very different ways to build very different docs sites.
Fuma’s approach stems from a broader diagnosis: modern web frameworks are too abstracted. They feel “magically” easy to use because complexity is hidden; yet this also obscures the underlying logic, mechanics, and inevitable tradeoffs. For example, beginner developers may use Next.js’s Metadata API with no idea of how the meta tag works, or put logic in a Server Component with no idea of what the computation costs.
Too much abstraction prevents developers from being able to really see, understand, and modify code. His aim with Fumadocs is thus to be “less-magic.” The framework puts the route files in your repository, has you create the search handler, lets you call the content loader from your own code, and can copy UI components directly into your codebase via the CLI.
Fuma explicitly defines the framework as not opinionated. The term “opinionated software” refers to a framework or library which enforces a set of conventions, guiding users toward one “correct” way of building. (It is sometimes conflated with having an opinion at all or applied as universally favorable.) Opinionated software, with its strong defaults and “right” path for building, clashes with Fuma’s goals of composability, breakability, and less abstraction.
Fumadocs is thus a less magic, less opinionated framework.
Fuma does still recognize the need to help developers with immediate usability and completeness. To this end, he has designed the UI library as a more opinionated layer of the framework, with a strong default visual design. In this way, developers can immediately create docs that look elegant while retaining the ability to modify each modular piece. (Which means they could swap in their own UI entirely, if desired.)
“The hardest problem of Fumadocs is balancing the two extremes of users,” he said. “On one hand are the developers who don’t want to make any modifications and just want a fast and easy start. On the other hand are those who want to customize everything, so that you can barely recognize the original form.”
This balancing act is a challenge for most frameworks and library authors, and is just one of the many tradeoffs Fuma Nama has thought closely about.
A black box and a compiler
Shipping code as a package, a common library default, has been a carefully considered decision for Fuma.
“The package is a kind of black box for most developers, unless they track the source code,” said Fuma. “Of course, you can still modify the code by patching it. But once you put it inside a package, you don't actually know what's happening inside.
This problem gets worse at scale. “The more logic you build in the package, it’s like putting more code in the black box,” he said.
The alternative approach, the shadcn/ui model of copying components directly into your codebase, avoids the black box problem. But it comes with its own drawbacks.
“The maintenance cost is always given to you,” he said. “And every time the framework improves or makes a new feature, you have to do a lot of code refactoring. At some point, it doesn’t make sense anymore.”
Fuma navigates this bargain in Fumadocs by building in progressive escape hatches. The package is still the primary model, while the CLI (shadcn/ui-inspired) helps developers who reach a need for more granular customization. The CLI works per component and can go even finer, pulling a single slot of a layout (for example, only the table of contents). The component copy belongs to the developer and the slots prop plugs it back into the surrounding structure, so future releases can keep updating from the Fumadocs package without overwriting it.
Behind the scenes, Fuma Nama cites the CLI as one of the more difficult pieces to build. It’s effectively a compiler which needs to take the original package component and transform it into standalone files compatible with the destination project and framework.
“You have to transform a working component in a package back into something separated, isolated into a file that can be downloaded into the codebase,” he explains. “I had to learn all the different frameworks and do a lot of testing to ensure the AST is right.” (Abstract Syntax Tree transformation involves parsing the component’s source file into a tree, rewriting its import paths to match the destination, and adapting syntax.)
With the CLI, the framework’s four modular layers are complete: Content, Core, UI, and CLI.
Fuma describes Fumadocs as “a bunch of utilities and MDX plugins.” His favorite integration is Story, which is built for component library docs. Story is a place Fumadocs really shines, since interactive components can’t be showcased in Markdown-only, which is a limiting factor for less flexible docs frameworks.
“Even if I started again from scratch, I think Fumadocs would probably be the same shape,” said Fuma. It’s a framework which can be truly broken, and which has been meticulously designed to be that way.
The Fumadocs design credo
Fuma’s design philosophy for docs tends towards the minimalist user experience, with deep attention to every detail; his visual design sensibilities align with his belief in simplicity in code.
“I’m drawn to the abstraction of shape in design art. I try to incorporate this in my own designs to depict something out of geometric shapes,” he said. “The logo of Fumadocs is a circle that I would call the moon, Luna.”
“I spent a lot of time just crafting the details. The default layout has been changed a lot of times, with some very small iterations on each version,” he said.
Fuma Nama believes that “fancy eye-catching UI” is more suited for a landing page, while documentation pages should focus on content and a simple reading experience.
The table of contents (TOC) design is one example of an unobtrusive yet deeply considered visual aspect of Fumadocs.
“I was inspired by the Clerk documentation slider. But I wanted to do it differently and make it in a more beautiful way,” he said. The mechanics of the slider are tricky due to server-side rendering. The server draws the outline but can’t measure the browser, so the interactive part needs to be rebuilt client-side. It works by tracing the outline’s shape as an SVG path and applying it as a CSS mask, with a glowing block sliding behind it so the “active section” highlight travels along the line.
“People might not notice, I suppose,” Fuma reflected. But the small details are worth doing anyways, and it’s clear his attention to nuance in visual design flows from his broader care for developer and reader experience.
“Oftentimes you’re not just making the solution, you’re designing it,” he said. “You have to try different approaches until it works in a balanced way.”
Perfect software
The next iteration of Fumadocs Plus will include more simple handling, to better serve beginners as well as AI. “Less complexity is much better for AI,” Fuma explained. “Because as we know, AI can really hallucinate things.”
He notes that he’s getting fewer issues than before, likely because of agents, who won’t open an issue but instead work around a problem. It’s become harder to build a feedback loop. “If agents don’t report bugs, then I can’t fix them,” he said. “But I’m still actively working on all the projects and keeping the issues as low as possible.”
He welcomes contributions from the open-source community. “If you want to contribute a feature or anything to my repos, just open an issue and say you want to contribute,” he said. “I will be happy to review it.”
“I hope Fumadocs will be the documentation framework for the web,” he said. “And I want to keep making it the standard for UI.”
Fuma is also building out other open-source software, including active development of tegami, a tool to manage changelogs and versioning, and fumadb, a database API for libraries.
“I think open-source will grow bigger as more companies start to recognise and give back to the open-source community,” he said. He noted that AI is reshaping the ecosystem, lowering the maintenance cost of projects and giving more space to maintainers.
Fuma references Daishi Kato as his open-source inspiration, especially his RSC framework Waku and state management library Jotai.
“Waku is really underrated. The key idea is that it’s very minimal and composable, which is why I built Fumadocs and many other projects on top of it,” he said. Their philosophical alignment is apparent; the Waku website describes the framework as “lightweight” and a “fun developer experience.”
Fuma has spent immense time working on his open-source projects, with painstaking effort that is often invisible. He considers all his projects to be his treasures and continual works-in-progress.
“I want to build perfect software,” he said. “Zero issues on my repositories, that’s kind of my goal.” If the perfect software exists, Fuma Nama may just be the one to build it.