Taylor Fang
Fumadocs
最初の助成対象プロジェクトとして、Fuma Nama 氏が手がける Fumadocs を発表できることを嬉しく思います。
Fumadocs は、美しく柔軟な React 向けドキュメントフレームワークです。このフレームワークは Core、Content、UI、CLI という 4 つのモジュール層で構成されています。アーキテクチャもビジュアルデザインも、コンポーザビリティ (組み合わせやすさ) とシンプルさという中核の哲学から導き出されたものです。各ライブラリは動作の仕組みが見える「ビルディングブロック」の集合であり、開発者は思い通りにドキュメントを変更・作成できます。ビジュアルデザインでは、洗練された高性能なコンポーネントが細部まで丹念に作り込まれています。人間にとっても LLMs にとっても、圧倒的に高速な読み込み体験です。
Fumadocs は Vercel Turborepo、shadcn/ui、BetterAuth、Unkey をはじめ、多くのプロジェクトで採用されています。それぞれのサイトがまったく異なる見た目になっていることこそ、Fumadocs の コンポーザビリティ を物語っています。もちろん、General Translation も自社のドキュメントに Fumadocs を使用しています。
Fumadocs の作者である Fuma Nama 氏は、開発者体験について深く考え抜いてきました。読みやすさを意識したコンテンツの構成から、抽象化の削減、保守性とカスタマイズ性の両立に至るまで、フレームワークのあらゆる層と細部に並外れた検討が注がれています。
私たちは Fuma Nama 氏にとって初となるインタビューの機会を得て、3 年以上に及ぶ Fumadocs 開発の歩みと、それ以前から続く長年の オープンソース 開発について伺いました。 (彼が昨年高校を卒業したばかりだということをご存じでしたか？)
以下では、Fuma Nama 氏がコードファイルを眺めることでプログラミングを学んだ経緯、「押し付け的なソフトウェア (主張のあるソフトウェア) 」に対する見解、氏のライブラリが「魔法を減らす」アプローチを取る理由、オープンソース が本質的にグローバルである理由、そしてドキュメントの読者体験に関する哲学を紹介します。氏の名前の由来や、Fumadocs のロゴが月から着想を得ていることなど、随所にイースターエッグも散りばめられています。
コンピューターの鮮やかな世界
Fuma Nama は香港で育った。6歳のとき、家族がコンピューターを買った。子どもの頃にワールド・ワイド・ウェブをさまよい歩いた日々について彼は書いている。そこで初めて「コンピューターの鮮やかな世界」に出会ったのだという。彼のソフトウェアに対する感覚は、魔法めいていて遊び心に満ちている。小学生の頃には、Unity のサンドボックスゲームをつぎはぎでつくり、プレーヤーが砂漠、月、廃墟と化した都市、山、森といったさまざまな風景の中で車と飛行機を乗り換えられるようにした。
「概念としてのソフトウェア」という捉え方にたどり着いたのは、もっと後のことだ。彼がコードを覚えたのは、ビデオゲームの改造とリバースエンジニアリングを通じてだった。コードを眺め、手を加え、ゲーム内で何が変わるかを見る。そうやって C# を身につけていったと彼は語る。
「ちょっとおかしな話ですよね。僕はファイルからコードを学んだんです。膨大な量の JavaScript を目にして、それをひたすら読む、という感じで」と彼は言う。「ドキュメントの類いは一切見ませんでした。コードそのものだけです」
(意図したわけではないにせよ) 「一次資料」に直接あたったことで、Fuma は骨格となる認知的な原理を深いレベルで理解するようになった。身についたのは、挙動に貼られたラベルではなく、フレームワークの背後にある思考の枠組みだった。ソフトウェアアーキテクチャで好きな部分は何かと尋ねると、Fuma は今でも Java の昔ながらの OOP (オブジェクト指向プログラミング) を挙げる。ほとんど過激なほどにシンプルな選択だ。
「オブジェクトという考え方はとても美しいんです。僕はクラスを拡張するという発想で考えます」と彼は言う。「Java でも JavaScript でも、他の多くの言語でも同じように働く、普遍的なモデルなんです」
Fuma Nama は自身のウェブサイトで自らを「open sourcerer (オープンソースの魔法使い) 」と称している。C# をゼロから学んだ彼が、React.js や Vite といった現代のウェブ開発フレームワークを「輝いていて魔法のようだ」と表現するのも無理はない。彼にとってソフトウェアとは、創造の可能性に彩られた体験なのだ。
「まる一日エディタに触れないと、どうにも気分が晴れないんです」と Fuma は言う。「旅行中でさえ、起きて最初にすることはコンピューターを開き、エディタを開くことです。自分が何をしているのか分かっていないときもありますが、とにかくエディタを開きたいんですよね」
「他の人が絵を描くことに感じるものを、僕はコードを書くことに感じているんです」と Fuma は語った。
オープンソースのエコシステム
Fumaは、オープンソースのライブラリを、数多くの開発者たちのビジョンと努力が積み重なったものとして強く意識している。
「大勢の人が関わり、多大な労力をかけて設計されたアイデアに、自分の手で触れられる。それが面白いんです」とFuma Namaは語る。「自然や地球を感じるような感覚ですね。世界中の人たちを実際に感じ取ることができる」
「たとえば[React]のServer Componentは、多くの優秀な頭脳が生み出したものです。RFCのプロセスがあったおかげで、Reactのコアメンバーだけでなく、大勢の開発者が関わっていました」と、彼はRequest For Commentsのプロセスに触れながら語った。
後にFumadocsとなるものを作り始めたとき、Fumaは当初それを「Next-docs」と呼んでいた。
「Next.jsの正式なドキュメントフレームワークを作れたら面白いんじゃないかと思ったんです。かなり無謀な野心でしたけどね」と彼は言う。「でもあれは実験でした。App Routerの時代にServer Componentが登場したばかりの頃で、まだ試したことのない興味深いパターンだったんです。私にとって、コードそのものが試してみたいおもちゃのようなものなんです」
彼はその後、公式ドキュメントと紛らわしくならないよう、フレームワークの名前をFumadocsに変更した。(Fuma Namaという名前は、軽くてふんわりしたものを表す日本語の「ふわふわ」をもじった遊び心のある言葉遊びから来ている。理想的な開発者体験、とも言えるだろう。)
Fumadocsはオープンソースコミュニティの手厚い支援を受けて成長してきた。Fumaが何より嬉しいのは、建設的なフィードバックという形で返ってくる反応だ。
「質問が添えられた反応や、フレームワークの改善につながるものなら何でも大好きです」と彼は言う。Fumaは今でも、開発者のAnthony Shewが2年前に立てたissueを参照している。その機能リクエストの中で、Shewは、Fumadocsの設計意図が「魔法を減らし、コンポーザビリティを高める」というビジョンに大きく傾いていることを見抜いていた。
「彼は大規模なプロジェクトで[Fumadocs]を採用した最初の一人でした」とFumaは語る。「本当に具体的で価値のあるフィードバックをくれました。プロジェクトの目指すところをきちんと理解し、気にかけてくれていた。それが私には驚きでした」
Fumadocsはその後GitHubで13,000を超えるスターを獲得するまでに成長し、Vercel、Unkey、Orama、そして私たち自身といった企業に利用されている。この3年間、Fuma Namaは学業やその他の務めの合間に何百時間も費やしながら、フレームワークの開発と保守を続けてきた。
Fuma Namaのものづくりへの探求の根底には、Web開発フレームワークとソフトウェア設計に対する、より深い哲学がある。
抽象化を減らし、押し付けを減らしたソフトウェア
Fumadocs ドキュメントの Philosophy セクションで、Fuma は中心となる主張をこう定義しています。Fumadocs は「壊せる」ドキュメントフレームワークとして作られている、と。
ここで言う「壊せる」とは、開発者がフレームワークのどの部分でも分解し、作り直せることを指します。Fumadocs の精神は、単に動くドキュメントが欲しい人ではなく、自分固有のニーズ・好み・美意識に合わせた「完璧なドキュメント」を作りたい人に応えることにあります。
「本当に、本当にコンポーザブルなシステムが必要なんです」と彼は言います。「十分に完成された、それでいて極めてコンポーザブルなフレームワークです」。Fumadocs が開発者に提供しようとしているのは、モジュール化された理解しやすいレゴのようなパーツです。それらをまったく異なる形で組み合わせることで、まったく異なるドキュメントサイトを作れるようにする、という発想です。
Fuma のアプローチは、より大きな問題認識から生まれています。現代のウェブフレームワークは抽象化が行き過ぎている、というものです。複雑さが隠されているため「魔法のように」使いやすく感じられますが、その一方で背後にあるロジックや仕組み、避けられないトレードオフも見えなくなってしまいます。たとえば初心者の開発者は、meta タグの仕組みを知らないまま Next.js の metadata API を使ったり、計算コストを意識しないまま Server Component にロジックを置いたりするかもしれません。
抽象化が過剰だと、開発者はコードを本当の意味で見て、理解し、書き換えることができなくなります。そこで彼が Fumadocs で目指したのは「魔法を減らす」ことでした。このフレームワークは、ルートファイルをあなたのリポジトリに置き、検索の handler はあなた自身に作らせ、コンテンツの loader はあなたのコードから呼び出す形にし、CLI を通じて UI コンポーネントを直接あなたの codebase にコピーできるようにしています。
Fuma はこのフレームワークを、押し付け的 (opinionated) ではないものとして明確に定義しています。「opinionated なソフトウェア」とは、一連の慣習を強制し、ユーザーを一つの「正しい」作り方へと導くフレームワークやライブラリを指す言葉です (単に方針を持っていることと混同されたり、常に良いことのように使われたりすることもあります) 。強力なデフォルトと「正しい」構築方法を備えた opinionated なソフトウェアは、コンポーザビリティ、壊せること、抽象化の少なさという Fuma の目標と衝突します。
つまり Fumadocs は、魔法が少なく、押し付けの少ないフレームワークなのです。
とはいえ Fuma は、すぐに使えることや完成度の高さで開発者を助ける必要性も認識しています。そのために彼は、UI ライブラリをフレームワークの中でより opinionated な層として設計し、強力なデフォルトのビジュアルデザインを与えました。これにより開発者は、すぐに洗練された見た目のドキュメントを作りながら、モジュールごとに手を加える余地も保てます (望むなら UI を丸ごと自前のものに置き換えることもできます) 。
「Fumadocs で最も難しい問題は、両極端なユーザー層のバランスを取ることです」と彼は言います。「一方には、一切手を加えず、ただ素早く簡単に始めたい開発者がいます。もう一方には、元の形がほとんど分からなくなるほど、あらゆるものをカスタマイズしたい人たちがいます」。
このバランス調整は、ほとんどのフレームワークやライブラリの作者にとっての難題であり、Fuma Nama が深く考え抜いてきた数多くのトレードオフのうちの一つに過ぎません。
ブラックボックスとコンパイラ
多くのライブラリの既定である「packageとしてコードを配布する」という選択は、Fumaにとって熟慮の末の決断だった。
「packageは、source codeを追いかけない限り、ほとんどのdeveloperにとって一種のブラックボックスです」とFumaは語る。「もちろん、パッチを当ててコードを書き換えることはできます。しかし、いったんpackageの中に入れてしまうと、内部で何が起きているのかは実際には分からなくなります」
この問題は規模が大きくなるほど深刻になる。「packageに組み込むロジックが増えるほど、ブラックボックスに放り込むコードが増えていくようなものです」と彼は言う。
もう一方のアプローチ、つまりcomponentを直接自分のcodebaseにcopyするshadcn/ui方式なら、ブラックボックス問題は避けられる。しかし、こちらにも欠点がある。
「メンテナンスコストは常に自分に降りかかってきます」と彼は言う。「しかもフレームワークが改善されたり新機能が追加されたりするたびに、大量のコードのリファクタリングが必要になります。どこかの時点で、もう割に合わなくなるのです」
Fumaはこのトレードオフに対し、Fumadocsに段階的な「逃げ道」を組み込むことで折り合いをつけている。中心となるモデルは依然としてpackageであり、その上でCLI (shadcn/uiに着想を得たもの) が、より細かなカスタマイズを求めるdeveloperを支える。CLIはcomponent単位で動作し、さらに細かく、レイアウトの単一のslot (たとえばtable of contentsだけ) を取り出すこともできる。componentのcopyはdeveloperの所有物となり、slots propによって周囲の構造に組み込み直されるため、以後のreleaseでもFumadocsのpackage側の更新を、上書きされることなく取り込み続けられる。
舞台裏では、Fuma NamaはCLIを構築が最も難しかった部分のひとつに挙げている。これは実質的にコンパイラであり、元のpackageのcomponentを受け取って、destinationのprojectとフレームワークに適合したstandalone filesへと変換する必要がある。
「packageの中で動いているcomponentを、切り離されて独立した、codebaseにdownloadできるファイルへと戻してやる必要があります」と彼は説明する。「ASTが正しくなるように、あらゆるフレームワークを学び、大量のテストを行う必要がありました」 (抽象構文木の変換では、componentのソースファイルをtreeへとパースし、そのimportのpathをdestinationに合わせて書き換え、構文を適応させる作業が伴う。)
CLIによって、フレームワークの4つのモジュール層が揃った。Content、Core、UI、そしてCLIである。
Fumaは、Fumadocsを「ユーティリティ群とMDX pluginの集まり」だと説明している。彼のお気に入りのintegrationは、componentライブラリのドキュメント向けに作られたStoryだ。Markdownだけではインタラクティブなcomponentを見せることができず、それが柔軟性に欠けるドキュメントフレームワークの制約となる。だからこそ、StoryはFumadocsの真価が発揮される場所なのだ。
「たとえ一からやり直したとしても、Fumadocsはおそらく今と同じ形になったと思います」とFumaは語る。それは本当に「壊せる」フレームワークであり、そうあるべく緻密に設計されてきたフレームワークなのだ。
Fumadocs のデザイン信条
Fuma のドキュメントに対するデザイン哲学は、細部へのこだわりを徹底しながらミニマルなユーザー体験を追求するものだ。そのビジュアルデザインの感性は、コードにおけるシンプルさへの信念と地続きになっている。
「デザインアートにおける形の抽象化に惹かれます。自分のデザインでもそれを取り入れ、幾何学的な形で何かを表現しようとしています」と彼は語る。「Fumadocs のロゴは円で、私はそれを月、Luna と呼んでいます」
「細部を作り込むことにかなりの時間を費やしました。デフォルトのレイアウトは何度も変更していて、バージョンごとにごく小さな改良を重ねています」と彼は言う。
Fuma Nama は、「派手で目を引く UI」はランディングページにこそ向いており、ドキュメントページはコンテンツと読みやすさに集中すべきだと考えている。
目次 (TOC) のデザインは、Fumadocs の控えめでありながら深く考え抜かれたビジュアル面を示す一例だ。
「Clerk のドキュメントのスライダーに触発されました。でも、違うやり方で、もっと美しい形にしたかったんです」と彼は語る。このスライダーの仕組みは、サーバーサイドレンダリングが絡むために厄介だ。サーバーはアウトラインを描画できるが、ブラウザ側の寸法を計測できないため、インタラクティブな部分はクライアントサイドで組み立て直す必要がある。具体的には、アウトラインの形状を SVG パスとしてトレースし、それを CSS マスクとして適用したうえで、光るブロックをその背後でスライドさせる。こうして「アクティブなセクション」のハイライトが線に沿って動いていく。
「たぶん、誰も気づかないでしょうね」と Fuma は振り返る。それでも、こうした小さなディテールには手をかける価値がある。ビジュアルデザインの機微への彼のこだわりが、開発者と読者の体験を思う姿勢から自然に生まれていることは明らかだ。
「多くの場合、解決策をただ作っているのではなく、デザインしているのです」と彼は言う。「バランスよく機能するようになるまで、さまざまなアプローチを試すしかありません」
完璧なソフトウェア
Fumadocs Plus の次のバージョンでは、初心者にも AI にも扱いやすいよう、よりシンプルな設計が取り入れられる予定です。「複雑さが少ないほど、AI にとってはずっと good です」と Fuma は説明します。「ご存じの通り、AI は平気でハルシネーションを起こしますからね」
彼によれば、報告される issue は以前より減っているといいます。おそらくエージェントの影響で、issue を立てずに問題を回避してしまうためです。フィードバックループを築くのが難しくなっている、というわけです。「エージェントがバグを報告しなければ、私には直しようがありません」と彼は言います。「それでも、すべてのプロジェクトに積極的に取り組み、issue はできる限り少なく保っています」
彼はオープンソースコミュニティからの貢献を歓迎しています。「私のリポジトリに機能でも何でも貢献したいなら、issue を立てて『貢献したい』と言ってください」と彼は言います。「喜んでレビューします」
「Fumadocs が web のためのドキュメンテーションフレームワークになることを願っています」と彼は言います。「そして、UI の標準であり続けさせたいですね」
Fuma は他のオープンソースソフトウェアも手がけており、チェンジログとバージョニングを管理するツール tegami や、ライブラリ向けのデータベース API である fumadb を活発に開発しています。
「より多くの企業がオープンソースコミュニティの価値を認め、還元し始めるにつれて、オープンソースはさらに大きくなっていくと思います」と彼は言います。また、AI がエコシステムを作り変え、プロジェクトのメンテナンスコストを下げ、メンテナーにより多くの余裕をもたらしているとも指摘しました。
Fuma は自身のオープンソース活動の原点として Daishi Kato を挙げます。とりわけ、彼の RSC フレームワーク Waku と状態管理ライブラリ Jotai です。
「Waku は本当に過小評価されています。重要なのは、非常にミニマルでコンポーザブルだということ。だからこそ私は Fumadocs をはじめ多くのプロジェクトをその上に構築したのです」と彼は言います。両者の思想的な一致は明らかで、Waku のウェブサイトもこのフレームワークを「軽量」で「楽しい開発者体験」と表現しています。
Fuma は自身のオープンソースプロジェクトに膨大な時間を注いできましたが、その地道な労力の多くは表には見えません。彼はすべてのプロジェクトを自分の宝であり、終わりのない進行中の作品だと考えています。
「私は完璧なソフトウェアを作りたいのです」と彼は言います。「自分のリポジトリの issue がゼロになること、それが私の目標のようなものです」もし完璧なソフトウェアが存在しうるなら、それを作り上げるのは Fuma Nama なのかもしれません。