マイグレーションコード自作して File-Based Routing に自動移行！！ ~250 ページの歴史的経緯を添えて~

WinTicket Webチームは、ユーザーが操作するアプリケーションだけでなく、社員が操作する管理画面の開発も行っています。 管理画面では、各社員の権限を基に、適切な画面の閲覧権と操作権を管理しています。

しかし、経年劣化・歴史的経緯による権限管理処理の複雑さや、コードベースのルーティング管理の煩雑さが課題となっていました。

今回はマイグレーションコードを自作して、250 ページにわたる画面を React Router から TanStack Router に全て置き換えた背景や手法をお話します。

Transcript

1. マイグレーションコード自作して File-Based Routing に自動移行！！ ~250 ページの歴史的経緯を添えて~ 株式会社WinTicket 加藤 零 2024/08/27 Muddy Web #9
2. 加藤 零 - kato, rei C 2023年 株式会社サイバーエージェント新卒入P C 株式会社 WinTicket 所# C # Web Speed Hackathon 2024 作問者 自己紹介 @cut0_ @cut0
3. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
4. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
5. 3 公営競技ネット投票サービ 3 競輪/オートレー 3 2019年4月リリー 3 市場シェアNo.1 #React #Fastly #Go #Kubernetes #Flutter #Cloud Run #Google Cloud #TypeScript #TanStack Query WINTICKET について
6. WINTICKET Web チームについて h チームメンバー 5 T h サービス本体の開発 + Web に関連する社内ツールの開G h WINTICKE7 h 管理画( h ダッシュボー h その他内製ツール
7. WINTICKET Web チームについて ) チームメンバー 5 3 ) ) WINTICKE' ) ) ダッシュボー ) その他内製ツール サービス本体の開発 + Web に関連する社内ツールの開q 管理画I →今回話す対象
8. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
9. TanStack Router 移行背景 ) 移行方# ) 移行過程での障害と解決策 話すこと ) 詳細なマイグレーションコードの解X ) TanStack Rouer が提供する詳細な機能について 話さないこと
10. TanStack Router 移行背景 s 管理面はクラシックな SPA で構成されていて SSR を行っていなe s GCS に HTML + JS + CSS をホスティングするシンプルな構“ s ルーティングライブラリの高度な機能を必要としなe s TanStack Router も最低限のルーティング機能だけを利用 前提
11. TanStack Router 移行背景 h React Router v5 を利T h 250 ページに及ぶルーティングを1つのファイルで管理R h RoleRoute, ProtectedRoute の混4 h 違いについては後述 障壁
12. TanStack Router 移行背景 ' params に型がつかなS ' History API を直接触っており、 ページパスに型がつかない 課題
13. 歴史的経緯① ~RoleRoute と ProtectedRoute~ 各社員の権限を基に、適切な画面の閲覧権と操作権を管理する必要がある 管理画面の規模拡大に伴い、より詳細な権限の管理が必要になった WinTicket では、従来のロールからより詳細な権限管理用のロール(新ロール) に移行中 前提 現在
14. 歴史的経緯① ~RoleRoute と ProtectedRoute~ ProtectedRoutX P より詳細な権限に基づいてページの閲覧権を管理するラッパーコンポーネント RoleRoutX P 旧ロールに基づいてページの閲覧権を管理するラッパーコンポーネント
15. TanStack Router 移行背景 E ルーティング管理ファイルの肥大P E ロール管理の複雑P E ルーティングに関連するもろもろの型が安全でな2 E そもそも React Router を v6 に上げられていない 課題 TanStack Router への移行 解決策
16. TanStack Router について ~ルーティング~ TanStack Router は下記の二種類のルーティング手段を提供している File-Based Routin — ディレクトリ・ファイルの構造に応じてルーティングルールを設 — src/pages/hoge/$fuda/index.tsx -> /hoge/:fuga にマッt — src/pages/hoge/$fuda/-Example.tsx -> - プレフィックスはルーティングに含まれなc — 他にも様々なルールがある ( ) 参考 Code Based Routin — 以前の管理面と同様にコードにルーティングルールを記載する
17. TanStack Router について ~ルーティング~ TanStack Router は下記の二種類のルーティング手段を提供している File-Based Routin — ディレクトリ・ファイルの構造に応じてルーティングルールを設 — src/pages/hoge/$fuga/index.tsx -> /hoge/:fuga にマッt — src/pages/hoge/$fuga/-Example.tsx -> - プレフィックスはルーティングに含まれなc — 他にも様々なルールがある ( ) 参考 Code Based Routin — 以前の管理面と同様にコードにルーティングルールを記載する →ルーティングファイル肥大化問題を解決するため採用
18. TanStack Router について ~型周り~ TanStack Router は routeTree.gen.ts ファイルを自動生成する ↓のようにページコンポーネントとディレクトリ、パス情報を集約したファイル
19. TanStack Router について ~型周り~ useParams, useNavigate, useSearch 等よく使う Hook に型が通る →id に型が通る →パスに型が通る
20. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
21. ページの移行 方針 (% 既存のルーティング用のコンポーネントを読み込む F% path プロパティを読み、同等のディレクトリを作成 ”% component プロパティの定義をたどり、2 で作成し たディレクトリにページコンポーネントを移動
22. ページの移行 方針 (% 既存のルーティング用のコンポーネントを読み込む F% path プロパティを読み、同等のディレクトリを作成 ”% component プロパティの定義をたどり、2 で作成し たディレクトリにページコンポーネントを移動
23. 障壁① ~RoleRoute と ProtectedRoute の混在~ RoleRoute, ProtectedRoute が同一のインター フェースで実装されていないため解析が煩わしい ProtectedRoute の実装を拡張し、RoleRoute を廃止 障壁 解決策
24. ページの移行 方針 (% 既存のルーティング用のコンポーネントを読み込む F% path プロパティを読み、同等のディレクトリを作成 ”% component プロパティの定義をたどり、2 で作成し たディレクトリにページコンポーネントを移動
25. ページの移行 src/pages-v2/campaigns/$campaignId ディレクトリを作成 src/pages-v2/admins ディレクトリを作成 src/pages-v2/admins/new ディレクトリを作成 src/pages-v2/campaigns ディレクトリを作成 ※pages-v2 ディレクトリは TanStack Router の File-Based Routing 用ディレクトリ
26. ページの移行 方針 (% 既存のルーティング用のコンポーネントを読み込む F% path プロパティを読み、同等のディレクトリを作成 ”% component プロパティの定義をたどり、2 で作成し たディレクトリにページコンポーネントを移動
27. ページの移行 import 文をたどり、ページコンポーネントのパスを算出 各ページコンポーネントを pages-v2 ディレクトリに移動する
28. AST の解析について AST の解析には jscodeshift を利用 ‡ JavaScript の codemod、TypeScript でも利用可i ‡ 左図のように AST を見ながらコーディングするのがq ‡ 類似のライブラリでは ts-morph が上げられQ ‡ 管理面リポジトリでは既に jscodeshift の環境が整ってい たため、今回は jscodeshift を利用 ‡ https://github.com/facebook/jscodeshif‘
29. ページの移行 方針 (% 既存のルーティング用のコンポーネントを読み込む F% path プロパティを読み、同等のディレクトリを作成 ”% component プロパティの定義をたどり、2 で作成したディレクトリに ページコンポーネントを移動 1 ~ 3 の手順を操作するためのファイルを作成
30. ページの移行 url  ページの URL を示す isUnstated  後述 filePath  移行後のファイルパス beforeDepth, afterDepth  移行前移行後のルートからの深さ componentPath  移行前のファイルパス
31. ページの移行 ページの実態は同一階層の コンポーネントが持つ 各種ロールのハンドリングは ここでおこなう
32. 障壁② ~3世代に渡る状態管理ライブラリの混在~ WinTicket 管理面では3種類の状態管理ライブラリが混在している unstatef y Class Component 時代の状態管理ライブラn y 一番の障壁 Recoiˆ y Hook ベースの状態管理ライブラリ TanStack Querq y 非同期状態の管理を得意とするライブラn y 最近 WINTICKET 本体は Redux から TanStack Query に移行した ( ) 参考 障壁
33. unstated について クラスコンポーネント時代の状態管理ライブラリ Y コンテナ → コンポーネントにロジックとステートを注入することで状態を管理 Y WinTicket では今回の移行とは別枠で黙々と移行するプロジェクトが走っている Y issue ページ自体が Close しており、メンテナンスされていない https://github.com/jamiebuilds/unstated
34. 障壁② ~3世代に渡る状態管理ライブラリの混在~ その他 unstated ページ側にロジックとステートを注入
35. 障壁② ~3世代に渡る状態管理ライブラリの混在~ ページの実態は同一階層の コンポーネントが持つ 各種ロールのハンドリングは ここでおこなう
36. 障壁② ~3世代に渡る状態管理ライブラリの混在~ ページの実態は同一階層の コンポーネントが持つ 各種ロールのハンドリングは ここでおこなう コンテナからページにステートとロジックを 注入するための層が必要
37. 障壁② ~3世代に渡る状態管理ライブラリの混在~ その他 unstated /$campaignId ├─ index.tsx : ルーティング用のコンポーネント └─ -CampaignDetail.tsx : ページの実態 ├─ -Injector.tsx : ロジックとステートを注入する層 /$campaignId ├─ index.tsx : ルーティング用のコンポーネント └─ -CampaignDetail.tsx : ページの実態
38. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 ルーティング処理の移行 05 移行してみて 06 おわりに
39. ルーティング処理の移行 前提 A react-router v5 が提供する Route コンポーネントを利用していた A Route コンポーネントは対象に RouteComponentProps で定義された型を インジェクトすH A ※v6 では非推奨 A RouteComponentProps の中でも、history, location, match のみが利用されていx A history : History オブジェクト。主に history.push でのページ遷移に利€ A location : History API の location インターフェー— A match : パスパラメータを取得するために利用
40. ルーティング処理の移行 要は 下記の変換ができればよい
41. ルーティング処理の移行 方針 4D location, history, match それぞれ Props で 展開されている → コンポーネント内で Hook を利用 ™D match.params を useParams に書き換p g from には前述の route-info.json を利用 tD location.search を location.searchStr に 書き換え
42. ルーティング処理の移行 方針 4D location, history, match それぞれ Props で 展開されている → コンポーネント内で Hook を利用 ™D match.params を useParams に書き換p g from には前述の route-info.json を利用 tD location.search を location.searchStr に 書き換え
43. ルーティング処理の移行 方針 4D location, history, match それぞれ Props で 展開されている → コンポーネント内で Hook を利用 ™D match.params を useParams に書き換p g from には前述の route-info.json を利用 tD location.search を location.searchStr に 書き換え
44. ルーティング処理の移行 方針 4D location, history, match それぞれ Props で 展開されている → コンポーネント内で Hook を利用 ™D match.params を useParams に書き換p g from には前述の route-info.json を利用 tD location.search を location.searchStr に 書き換え
45. ルーティング処理の移行 方針 4D location, history, match それぞれ Props で 展開されている → コンポーネント内で Hook を利用 ™D match.params を useParams に書き換p g from には前述の route-info.json を利用 tD location.search を location.searchStr に 書き換え もちろんこれは既存実装が統一されている場合の話です 実際は AST の変換をしやすいように 事前にコードを整える必要がありました
46. 障壁③ ~useHistory~ TanStack Router が useHistory Hook を提供していない 自前で実装する 障壁 解決策 useHistory とはq p History オブジェクトにアクセスするための Hooku p React Router v6 でも廃止
47. 障壁③ ~useHistory~ d History オブジェクトを直接利用している箇所が多いため、暫定的に 自前で実‡ d 基本的に History オブジェクトを直接操作したくないので、今後は TanStack Router が提供する純正の Hooks に移行する方b d useNavigate, useLocation, useSearch 等
48. 障壁③ ~useHistory~ 実装イメージ
49. 障壁③ ~generatePath~ ex) generatePath("/users/:id", { id: "42" }); /users/42 generatePath("/files/:type/*", { type: "img", "*": "cat.jpg", }); /files/img/cat.jpg React Router が提供するパス解決用の関数 o https://reactrouter.com/en/main/utils/generate-path
50. 障壁③ ~generatePath~ そもそも TanStack Router が generatePath を提供していない 課題 GitHub で React Router のソースを読み、自前で実装する 解決策
51. 障壁④ ~generatePath~ ポイント p React Router の特定の機能に依存していなV p 管理面で扱うには不要なロジックがあ$ p Warning、*のハンドリングE p 該当箇所 機能を絞って自前で実装する
52. 障壁④ ~generatePath~ 機能を削ぎ落としシンプルになった ライブラリが提供してくれるものも 自前で実装できるかも みたいなことはよくある
53. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
54. 移行してみて 想像以上に各ページのコードの見通しが良い D URL から対象ページの実装を たどりやすい D ページに付随するロールが一目 でわかる
55. 移行してみて 型が通るって最高だ →id に型が通る →パスに型が通る パラメータ、パスに型が通るので開発時も迷わず、タイポも検知できる
56. 移行してみて 最近はクエリパラメータのバリデーションも行っています →クエリパラメータに型 →スキーマ定義 g Zod, Valibot 等のバリデーション ライブラリを利用可G g 参考 g yup に基づいたスキーマを提供
57. 今後の展望 unstated の脱b B 現在チーム一丸で進行中 u B -Injector.tsx が存在する unstated が利用されているページを TanStack Query に移行u B -Injector.tsx が生えたことで、unstated に依存しているページの特定が楽に useHistory の脱b B useNavigate, useParams, useSearch 等の TanStack Router が提供する Hook に移行
58. 目次 01 WINTICKET について 02 TanStack Router への移行背景 03 ページの移行 04 Hooks の移行 05 移行してみて 06 おわりに
59. 最後に f 移行を楽に進めるためにも、常日頃からコードに秩序をもたせるべ% f 大規模移行はいくら見通しを立ててもエッジケースに絶対に直面するので 地道に手を動かす必要があ9 f 大規模移行には腕力・覚悟・気合が必要
60. We are HIRING !!!  WINTICKET Web で働いてくれる人を募集していますF  圧倒的若手チーム（全員20代5  Web っぽいことだけに閉じずに CI/CD やインフラ周りを触る機会もアリ