Share
Embed
モノリシックなフロントエンドに境界を引いてコツコツ分割した話
JSConf JP 2026の資料です。
https://jsconf.jp/2026
Toshihisa Tomatsu
November 22, 2026
Transcript
41 slides
-
⾃⼰紹介 ©Linc' well inc. • 外松 俊尚(Toshihisa Tomatsu) • フロントエンド基盤チーム
EM • リモートワーク • 愛媛(2019)→東京(2026) • X: @toshi__toma 2 -
患者向けWebアプリ • • • • スマホ⼀つでクリニックでの診察やオンライン診療までをスムーズに受診できるUXを提供 予約‧問診‧診察‧決済などの機能を提供 約6年ほど開発‧運⽤ 技術スタック ◦
◦ ◦ ©Linc' well inc. React+TS react-router GraphQL 5 -
初期の構成 技術レイヤーなどで切られたよくある構成 扱うドメインやチーム数も少なく初期ではこれでスピードも出て問題なかった 〜 2024年 src/ ├── pages/ # ルーティング+画面の実装
├── components/ # 画面の実装や共通コンポーネント ├── graphql/ # 全画面ぶんのクエリ ├── lib/ hooks/ ... └── router.tsx ©Linc' well inc. 7 -
課題 • • • • チームを跨いでコードが密に依存(or しているように⾒える) ◦ ◦ 影響範囲が広い
あるコードが他の機能から使われているか、毎回調べないと分からない ◦ 別々のドメインだが過度にコンポーネントが共有されていた ◦ チームで新しい取り組みを始めにくい 過剰な共通化 コードに対するチームのオーナーシップが曖昧 新しい設計や技術を試したいが全体に影響する 組織は分かれたのに、コードはひとかたまりのままだった ©Linc' well inc. 10 -
社内の横断ワーキンググループで、4期かけて進めた 四半期ごとに組成される業務時間内の活動 3チームからワーキンググループに参加し、横断的な意思決定を進めた 期 主なゴール 2024年 3Q 分割の意義と⽅針を決め、各チームのメンバーから FB をもらう
2024年 4Q 2つのチームで移⾏を始めた 2025年 1Q 1チーム移⾏完了、3つ⽬のチーム着⼿、ESLint で依存ルールを導⼊ 2025年 2Q GraphQLの分割やその他ルール整備、ドキュメンテーション ©Linc' well inc. 12 -
モノリシックなアプリの分割について考えた • バックエンドで採⽤されているモジュラーモノリスを参考に ◦ • Shopify - Deconstructing the Monolith:https://shopify.engineering/deconstructing-monolith-designing-software-maximizes-developer-produ
ctivity デプロイ単位は1つのまま(モノリス)、内部をモジュール境界で分割。モジュール同⼠は公開イン ターフェースを通してだけ依存し、その境界をツールで守る ©Linc' well inc. 13 -
モジュラーモノリスで考えると? モジュラーモノリスのように、1つのアプリの中で境界が引かれ、依存関係が整理されている App/ルーティング • • 公開 公開 チームA ドメインA •
• 公開 共通のコード以外は、それぞ れのモジュールが持つ 外から触れるのは最⼩限の公 開モジュールだけ 依存は⼀⽅向で、循環がない ルールを強制できる チームB ドメインB ドメインC 共通(UI コンポーネント‧ロジック‧ライブラリ) ©Linc' well inc. 14 -
いきなりそこにいけるか? • 理想の状態と、当時のコードベースの間には⼤きな距離がある • 完全に分割するより前の中間地点が必要 ⽬指したい状態 2024年時点 モジュール分割され、それらは最⼩限の公開モジュールだ けで依存する 技術レイヤーの中でドメインが混ざり、ドメイン外から依
存されているものや境界が⾒えない 依存の向きが⼀⽅向で、循環がない 依存関係が複雑 pages -> components -> pagesみたいな依存の向きのコー ドもある 境界をはみ出したら、機械的に気づける 依存のルールなし 並⾏開発中で、機能開発は⽌められない ©Linc' well inc. 15 -
まずは粗くても境界を引いて分割する • まず得たいもの ◦ ◦ ◦ • ⾃チームの外への影響範囲を明確に(=この変更は⾃チームで⾒てる機能だけに影響が閉じる) コードのオーナーシップを明確に(=このコードは⾃チームで好きに進化させていく) アプリ全体ではなく段階的に新しい取り組みを開始できる
「チームが、実際よりずっと⼩さなアプリを開発しているように感じられる」状態を作りたかった Shopify Engineering「Under Deconstruction: The State of Shopify’s Monolith」より ◦ ⾃チームの範囲を理解すれば開発できる ◦ 新しい取り組みを⾃チームで⼩さく始められる ©Linc' well inc. 16 -
チーム(≒ドメインのまとまり)を軸にした分割 • チームは既にオーナーシップを持つドメインがある • 最初はチーム単位で⼤きめに分割し、中の分け⽅やディレクトリ構成はチームに任せた • ◦ 少なくともそこを軸に境界を引いて分割することができそう ◦ ◦
普段の開発サイクルや意思決定の単位と合っている 機能や細かいドメイン単位だと、適切な境界を設計できる⾃信が持てなかった チームの形が変わっても、ドメイン軸で増減する程度と予想(その程度ならファイル移動で追従で きる) ©Linc' well inc. 17 -
src/packs の下にチームを軸にディレクトリを作った • • • モジュールとして分割する新たな層(packsディレクトリ)を新設 バックエンドの packwerk(Rails のモジュラーモノリス化)に合わせて名前も packs
に揃えた packs の中の構成は⾃由 ディレクトリ構成 src/ ├── packs/ │ ├── payment/ # 決済 │ │ ├── pages/ # 決済の画面 │ │ ├── components/ # 決済で使うコンポーネント │ │ └── exports/ # 外部に公開 │ ├── telemedicine/ # オンライン診療 │ ├── .../ │ └── insurance/ # 保険診療 ├── pages/ # *.page.tsx と共通機能だけ残す ├── components/ lib/.. # 共通(コンポーネント・ロジック・etc) └── router.tsx ※ イメージ ©Linc' well inc. 18 -
依存関係のルール • • • pages → packs → 共通 の向きを決め、packs
の中には exports 経由でしか触れないように packs間は⼀部相互依存が残るが現段階では許容した eslint-plugin-import の no-restricted-pathsでルールを適⽤ pages(ルーティング‧URL パラメータの解析) exports exports packs/A packs/B 共通(components / lib / ui など) ©Linc' well inc. 19 -
exports/ は外部に公開しているモジュール • • exportsには外部に公開するモジュールをre-exportする 外から使われているものが⼀覧でき、それ以外は安⼼して変えられる • 元々packs のバレルファイル(index.ts)から公開していたが、バンドルサイズの増加につながっ たので、exports
ディレクトリからファイル単位で公開するようになった ◦ 「このファイル、他のドメインから使われてる?」を毎回調べなくてよい packs/payment src/pages pages/ ◦ import OK exports/ 外部に公開 (re-export) components/ packs/insurance internal/ × 中を直接 import は warning ©Linc' well inc. 20 -
移⾏作業 • チームでオーナーシップを持つドメインのコードを全部packsに移動 • pagesやcomponentsなどには共通コンポーネントや共通機能だけを残す • 外部から依存されるモジュールはexportsディレクトリから公開 移⾏前 src/ ├──
pages/ # ルーティング+画面の実装 ├── components/ # 画面の実装や共通コンポーネント ├── graphql/ # 全画面ぶんのクエリ ├── lib/ hooks/ ... └── router.tsx 移⾏後 src/ ├── packs/ │ ├── payment/ # 決済 │ │ ├── pages/ # 決済の画面 │ │ ├── components/ # 決済で使うコンポーネント │ │ └── exports/ # 外部に公開 │ ├── telemedicine/ # オンライン診療 │ ├── .../ │ └── insurance/ # 保険診療 ├── pages/ # *.page.tsx と共通機能だけ残す ├── components/ lib/.. # 共通(コンポーネント・ロジック・etc) └── router.tsx ※ イメージ ©Linc' well inc. 21 -
使ったのはディレクトリと ESLint だけ • • 新しいツールを増やさなかったので、すぐ始められて不確実性が低かった packs側にファイルを移動させていくだけで、効果が出る ◦ ◦ ◦
• 関連するコードが集まる チームがオーナーシップを持っているコードが明確に 他のドメインから依存されているモジュールが可視化 ファイル移動だけで挙動を変えないのでリスクが低かった src/ ├── pages/ # ルーティング+画面の実装 ├── components/ # 画面の実装や共通コンポーネント ├── graphql/ # 全画面ぶんのクエリ ├── lib/ hooks/ ... └── router.tsx src/ ├── packs/ │ ├── payment/ # 決済 │ │ ├── pages/ # 決済の画面 │ │ ├── components/ # 決済で使うコンポーネント │ │ └── exports/ # 外部に公開 │ ├── telemedicine/ # オンライン診療 │ ├── .../ │ └── insurance/ # 保険診療 ├── pages/ # *.page.tsx と共通機能だけ残す ├── components/ lib/.. # 共通(コンポーネント・ロジック・etc) └── router.tsx ※ イメージ ©Linc' well inc. 22 -
結論:約2年で、分割は⼀区切り • • • • 担当チームが明確な機能は移⾏できた 全チームが⾃チームの領域を持ち、外に公開しているモジュールも明確になった オーナーシップがあるコード(packs)は全体の約60%になった 約2年間でコードは約2倍になったが ◦
©Linc' well inc. pagesは約44%減、componentsは約22%減 24 -
移⾏は機能開発の「ついで」に進めた • • • • ⼿順書を作成 ⼤きな改修が⼊る画⾯は、改修前の下準備として packs へ移す まとまった機能は、ページ単位にこだわらず⼀括で移す
変更が主にファイル移動なのでレビューが簡単 ◦ ©Linc' well inc. 差分が⼤きい PR は、同期レビューで早くマージする 26 -
依存関係のルールを遵守するよりも移⾏を優先 • 移しながら依存も整理しようとしたが失敗した • 依存ルールは ESLint で検査するが、error ではなく warning にした
• warning の⼀覧が、依存関係違反コードのリストになる ©Linc' well inc. ◦ 「依存をきれいにしてから移す」はやらないことにした ◦ error にすると、違反を全部直すまで移⾏を進められない ◦ 依存関係のwarningは残り45件(2026年11⽉時点)なので解消も現実的 27 -
基盤チームで各チームの開発がpacks に収まるかを観察 • • • 各チームのPRを週次で⾒て、境界が適切かを観察 普段の開発が概ね⾃チームのpacksに収まっている → 境界が機能している 他チームのpacksを頻繁に変更している/複数のpacksを同時に変更している
→ 境界の引き⽅か、共 通化を⾒直すサインかも ©Linc' well inc. 29 -
チームがコードにオーナーシップを持つようになった • • • チームの領域が明確になり、GitHubのCODEOWNERSを設定するようになった ◦ 他チームの領域を触ると、⾃動でそのチームにレビュー依頼が⾶ぶ ⾃分たちの packs だけを触る
PR が増え、チーム間のコンフリクトも減った 「誰にレビューを頼めばいいか分からない」がなくなった 良い変化 • • レビュー先が明確になり、チームを跨いだリファクタリングが活発になった 施策の検討時に「この画⾯‧コンポーネントは⾃分たちがオーナーシップを持つべきコードか」を 議論するようになった ◦ ©Linc' well inc. 持つべきと判断したコードは、他チームの packs から⾃分たちの packs へ取り込んだ 31 -
チームで設計を議論しやすくなった • • • • 統⼀的な設計ルールは最⼩限にして、packsの中はチームで⾃由に決める ⾃チームの領域は意思決定がチームで閉じる チームで設計の⾒直しや新たなルール、プロセスを導⼊する事例が増えた 例 ◦
◦ ◦ ©Linc' well inc. チームで議論して設計ルールを作り、それに沿ってリファクタリング CodeRabbitでパスごとのチーム独⾃のレビュー指⽰ ⾃チームのテストカバレッジ低下をCIで落とす 32 -
チームごとのメトリクスを集計 • • • • パスで集計するだけで、どの指標もチームごとに出せる 週次でチームごとのレポートを出すようにした レポートの内容 ◦ ◦
◦ 週次リリースレポート ESLint の違反件数とその内訳 コード品質メトリクス ◦ ◦ ◦ PRのリストやその概要 設計からの逸脱がないか PRごとの変更ファイルのpacks率 週次リリースレポートの中⾝ ©Linc' well inc. 35 -
GraphQL の codegen もチームのpacksごとに持たせた Fragment Colocation などの新しい書き⽅も、チーム単位で導⼊できる アプリ全体ではなく段階的に新しい取り組みを開始できるようになった packs/xxx/codegen.yml(例) ファイルツリー(イメージ)
schema: src/graphql/schema.graphql src/ documents: ├── graphql/ - 'src/packs/xxx/**/*.{tsx,ts}' generates: src/packs/xxx/generated/: │ └── schema.graphql # スキーマは全体で共通 └── packs/ ├── payment/ preset: client │ ├── codegen.yml # pack ごとの設定 presetConfig: │ ├── generated/ # 専用の生成物 fragmentMasking: true └── insurance/ ├── codegen.yml └── generated/ ©Linc' well inc. 37 -
まとめ • • • • • • 組織の変化に合わせてコードも変化させた 特別な技術は使わず、ディレクトリと ESLint
で境界を引いた 軽量な移⾏内容で⼩さく始め、機能開発と並⾏して2年かけて移⾏した 境界ができたことで、チームがコードにオーナーシップを持てるようになった 分割したことで⽣まれた良い変化が多くあった AI時代になりコンテキストを絞れるのも良かった ©Linc' well inc. 39 -
コード分割は⼀区切り。ここからは、分けたからできることをやる • 境界の調整 • 不適切な依存の解消(違反‧循環‧共通コード) • 上記が落ち着いたら、monorepo化も選択肢に ◦ 複数チームが関わるドメインの実装は、今も相談しながら調整している ◦
依存関係の違反コードを完全解消、packs間の相互依存解消、過度に依存してるコードを⾒直す ◦ ◦ ◦ 境界をより厳密に パッケージ間の依存が明⽰される 特定のパッケージでしか使わないnpmライブラリを、そのパッケージの依存として分離できる(アップデートの影響範 囲が、そのチームに閉じる) よりチームごとに個別の設定を持ちやすい 変更の影響を受けるパッケージだけ検証できる ◦ ◦ ©Linc' well inc. 40