【ITニュース解説】I built a copy-paste JSON viewer for shadcn/ui

システムエンジニアを目指す上で、APIからのデータやシステムの内部情報を扱う機会は非常に多い。その際、データが「JSON」という形式でやり取りされることがほとんどだ。JSONはJavaScript Object Notationの略で、人間にも機械にも読みやすいデータの形式として広く使われている。しかし、単に受け取ったJSONデータをそのまま表示するだけでは、非常に読みにくく、データの構造を把握するのに苦労するという問題があった。特に、入れ子構造が深かったり、データ量が多かったりすると、どこに何の情報があるのか見つけ出すのが困難になる。

今回紹介する「json-view-cn」は、そうしたJSONデータの表示に関する課題を解決するために開発された新しいツール（コンポーネント）である。これは、開発者がアプリケーション内で生JSONデータを美しく、そして機能的に表示できるように設計されている。多くのアプリケーションでは、デバッグ画面やAPIのレスポンス表示などで生のJSONを表示する必要があるが、既存の方法では読みづらかったり、開発者が利用しているUIフレームワーク「shadcn/ui」の見た目と合わなかったりする問題があった。json-view-cnは、まさにそのギャップを埋めるべく、「shadcn/ui」に最適化された形で提供されている。

json-view-cnの最大の特徴は、単にJSONを表示するだけでなく、データをツリー形式で「折りたたんだり」「展開したり」できる点にある。これにより、まずは全体の構造をざっくりと把握し、必要に応じて詳細な部分だけを開いて確認するといった、効率的なデータ閲覧が可能になる。さらに、データ型に応じて色が異なる「シンタックスハイライト」機能も搭載されており、文字列、数値、真偽値などが一目で区別できるようになっているため、視認性が大幅に向上する。このハイライト機能は、ライトモードとダークモードの両方に対応し、Tailwind CSSというスタイリングフレームワークを通じて色を自由にカスタマイズできるため、開発中のアプリケーションのテーマに完璧に合わせることが可能だ。

他にも、開発者の生産性を高めるための便利な機能が満載だ。例えば、JSONデータの各行にマウスカーソルを合わせると、その行の内容をクリップボードにコピーできる機能がある。オブジェクト全体をコピーする際も、整形された読みやすいJSON形式でコピーされるため、別のツールに貼り付けて確認する際にも非常に便利だ。長い文字列データは途中で切り詰められて表示されるが、マウスホバーで全体を確認できるツールチップも用意されている。また、データの表示深度を制御したり、インデントガイドが表示されたりすることで、より複雑なJSON構造も視覚的に把握しやすくなっている。キーボード操作にも対応しており、アクセシビリティも考慮されているため、マウスを使わずに効率的に操作することも可能だ。

このjson-view-cnは、shadcn/uiを利用しているプロジェクトに簡単に導入できる設計になっている。shadcn/uiの提供する「コンポーネントをコピー＆ペーストでプロジェクトに組み込む」というアプローチを踏襲しているため、npx shadcn@latest add ...コマンド一つで、このJSONビューアコンポーネントを自分のプロジェクトに組み込むことができる。組み込まれたコンポーネントは、プロジェクト内の指定されたパス（例：components/ui/json-view.tsx）に単一のファイルとして追加されるため、完全に開発者の管理下に置かれ、必要に応じて自由に修正や拡張ができるというメリットがある。これは、既存のnpmパッケージとしてインストールする方式とは異なり、依存関係の管理をシンプルにし、細かなカスタマイズを容易にするための重要なポイントだ。

開発者はこのコンポーネントを、次のように使用する。まず、import { JsonView } from "@/components/ui/json-view"のようにインポートし、あとはdataプロパティに表示したいJSONデータを渡すだけだ。例えば、<JsonView data={response} rootName="APIレスポンス" initialDepth={1} stringTruncate={60} />のように記述することで、APIからの応答データを「APIレスポンス」という名前で、最初の階層まで展開し、文字列は60文字で切り詰めて表示するといった制御が可能になる。

しかし、このjson-view-cnの開発にはいくつかの技術的な課題と、そこから得られた学びがあった。実際のアプリケーションで扱うデータは、厳密な意味での「JSON」形式だけではない。JavaScriptにはDate（日付）、Map（キーと値のコレクション）、bigint（非常に大きな整数）といった、JSONでは直接表現できないデータ型が存在する。また、関数やシンボルといったデータ型も含まれることがある。json-view-cnは、これらのJSONの範囲を超えるデータ型も適切に扱えるように設計されている。具体的には、DateオブジェクトであればISO形式の文字列に変換して表示したり、Mapをオブジェクト形式、Setを配列形式に変換して表示したりする。bigintやundefined、関数、シンボルなどは引用符なしで表示することで、文字列と誤解されないように工夫されている。これらの処理は、データがどのような型であってもエラーで停止することなく、可能な限り読みやすい形式で表示するよう配慮されている。

また、JSONデータを扱う上で避けて通れないのが「循環参照」の問題だ。これは、データ構造が自分自身を間接的に参照してしまう状況を指す。例えば、オブジェクトAがオブジェクトBを参照し、そのオブジェクトBが再びオブジェクトAを参照するといった場合だ。これを単純に処理しようとすると、無限ループに陥ってしまう。json-view-cnでは、この循環参照を正しく検出するために、単に「以前に見たオブジェクトかどうか」をチェックするのではなく、「祖先のオブジェクトを再び参照していないか」という視点でチェックを行う巧妙なアルゴリズムが採用されている。これにより、同じオブジェクトが異なるパスから複数回参照されているだけのケース（循環参照ではない）と、本当に循環しているケースを正確に区別し、無限ループを回避しつつ、正しくデータを表示することが可能になっている。

さらに、JSONデータに含まれる文字列のエスケープ処理も重要なポイントだ。JSONの仕様では、二重引用符、バックスラッシュ、改行などの特殊文字は、特定のルールに従ってエスケープ（特殊な記号の組み合わせに変換）する必要がある。例えば、"Hello\nWorld"のような文字列は、JSONファイル上では"Hello\\nWorld"と表現される。json-view-cnは、JavaScriptのJSON.stringify関数を応用し、文字列を一時的にJSON形式に変換してから、その結果から引用符を取り除くという方法で、これらの特殊文字を正しくエスケープして表示している。これにより、表示される文字列が実際のJSONファイルでどのように表現されるかを正確に視覚化できる。

このjson-view-cnは、MITライセンスの下で公開されており、誰でも自由に利用し、改良することができる。もしデータが正しく表示されないといった問題を発見した場合は、開発元に報告することで、さらなる改善に貢献することも可能だ。このように、json-view-cnは、システムエンジニアが日々の開発で直面するJSONデータの視認性という課題に対し、実践的な解決策を提供する、非常に有用なツールと言えるだろう。