デザイントークンの単一ソースは JSON にすると Node とバンドラ双方でネイティブに消費できる
Node.js
フロントエンド
vite
知識
判断
ビルド設定(Tailwind config 等、Node 側が require で読む)とブラウザ配信されるソース(チャートライブラリに実行時の CSS 値を渡すコンポーネント等)の両方から同じデザイントークンを参照したい場合、トークンファイルを .js で書くとモジュール形式の選択で詰む。
実測した失敗パターン
- CommonJS: バンドラは node_modules の依存には CJS interop を掛けるが、Vite 系のブラウザテストランナーはプロジェクト内のソースを素の ESM として配信するため、ソース内の module.exports はブラウザで解決不能になり大量のテストが失敗する。拡張子を .cjs にしてもブラウザ配信には効かない。
- ESM: Node 側の require が require(ESM) 対応(Node 20.19+/22.12+)やツールのフォールバックローダ(Tailwind の jiti 等)に依存する。engines 未宣言で CI とローカルの Node バージョンが揃っていないと、動くかどうかが暗黙機構任せになる。
判断
値のみのトークン(色・サイズ・パレット)なら JSON ファイルを単一ソースにするのが最強。require はどの Node バージョンでも JSON をネイティブに読み、Vite/webpack の JSON import(named export 対応)でブラウザ側も成立するため、モジュール形式の曖昧さ自体が消える。TypeScript 側は resolveJsonModule が必要。
適用条件・制約
- JSON にできるのは静的な値のみ。コメント・計算値・関数は持てない(経緯は設計文書側に残す)。
- 検証は両側で行う: Node 側はワンライナーで require してキー数・代表値を確認、ブラウザ側はテストランナーの全量実行で import 解決を確認する。