microCMSのリッチエディタ開発：設計・品質・使いやすさの実現手法

PRTIMES.DEVのエディター勉強会で話した内容です。
https://prtimes.connpass.com/event/358977/

1. #prtimes_editor 野崎洋平 microCMSのリッチエディタ開発 設計・品質・使いやすさ の実現手法
2. 自己紹介 2 #prtimes_editor 野崎洋平 / のざきようへい @ryusou_mtkh microCMSのプロダクトエンジニア リッチエディタの開発を担当しました。愛猫家。 ryusou
3. 意図せず、キャリアでの登壇がリッチエディタまみれになった人です 自己紹介 3 #prtimes_editor ・マークダウンエディタの方が好き ・元々リッチエディタ開発は苦手な部類でしたが、今回お話しする内容を実践していく うちにリッチエディタ開発が好きになりました。（リッチエディタ開発辛いポイント皆 さんはありますか.....？）
4. microCMSにて現行のリッチエディタをリリースして2年ほど運用 今日お話しすること 4 #prtimes_editor ・テスト戦略 ・使いやすさ など当初からの取り組みが、実際に 2年運用してどうだったのか？お話し します。 （たぶん）この資料をみればmicroCMS のリッチエディタ開発ができるはず
5. 目次 5 • 設計「技術選定・設計」 • 品質「テスト戦略」 • 使いやすさ「アクセシビリティ」 • 使いやすさ「HTMLにこだわる」 #prtimes_editor
6. 目次 6 • 設計「技術選定・設計」 • 品質「テスト戦略」 • 使いやすさ「アクセシビリティ」 • 使いやすさ「HTMLにこだわる」 #prtimes_editor
7. tiptapを採用 技術選定 7 #prtimes_editor • Headless WYSIWYG Editor • ProseMirrorベースで拡張がしやすい • スタイルはUIは独自に拡張できる バックエンド • DynamoDB • Node.js
8. 2年間運用してみてどうだった？ 技術選定 8 #prtimes_editor • tiptapで拡張性を保ちつつ、素早くリリースできた • その後のリリース追加でも困るケースはなし • tiptap自体の開発速度も速い。直近でもv3リリース 一方で更新の負荷が高い • tiptapのpackage(tiptap-extension-hogehoge)から飛んでくる大量の dependabot。まれに破壊的変更もあり。
9. DynamoDBにtiptapのJSONを保存 設計 9 #prtimes_editor • DynamoDBにgenerateJSON で保存 https://tiptap.dev/docs/editor/api/utilities/html • generateHTMLでJSONからHTMLを生成、コンテンツAPIのレスポンスなどで返 す。
10. 設計 10 #prtimes_editor 管理画面 backend コンテンツAPI DynamoDB JSON JSON HTML GET API POST API JSON, HTML 管理画面 ※簡略化したもの、実際とは異なる箇所があります
11. 設計2年間運用してどうだった？ 設計 11 #prtimes_editor • DynamoDBの入出力・最終的なHTMLレスポンスのテスト戦略が大事（後述） • tiptap-extensionとDynamoDB特有の考慮事項 ◦ tiptap-extensionの ...parent()で全てのプロパティを継承するとJSONサイ ズが肥大するので400MB制限に影響がある。 ◦ 拡張機能をむやみに使わない、必要なプロパティのみを使用するなどソース コードから検討する必要がある。 ◦ 「拡張機能をむやみに使わない」というのは運用負荷を下げる観点でも大事 ▪ 時にはProsemirrorで自分で書くという選択肢を持っておく
12. 目次 12 • 設計「技術選定・設計」 • 品質「テスト戦略」 • 使いやすさ「アクセシビリティ」 • 使いやすさ「HTMLにこだわる」 #prtimes_editor
13. 品質 13 #prtimes_editor 管理画面 backend コンテンツAPI DynamoDB JSON JSON HTML GET API POST API JSON, HTML 管理画面 ※簡略化したもの、実際とは異なる箇所があります
14. DBとの入出力はスモールテスト（ユニットテスト）で 設計 14 #prtimes_editor • カバレッジ100%を目標・維持 • JestでHTML→JSON、JSON→HTML変換が行われているかを担保 • コードベース上でのカバレッジは担保できる一方、実際にユーザーが生成している カバレッジが担保できていない（HTMLの組み合わせをあげると無限に近いなの で....）
15. 品質 15 #prtimes_editor 管理画面 backend コンテンツAPI DynamoDB JSON JSON HTML GET API POST API JSON, HTML 管理画面 ※簡略化したもの、実際とは異なる箇所があります
16. コンテンツAPI全体の検証は外形監視(Checkly)で実行 品質 16 #prtimes_editor • Checklyでの外形監視 https://www.checklyhq.com/ • コードベースで実装できる（Playwright風にも書ける） • tiptapの入出力＋アプリケーション実装の全体を検証している • 信頼性がある一方、カバレッジを計測できていない、担保できていないという課題 あり
17. 品質 17 #prtimes_editor 管理画面 backend コンテンツAPI DynamoDB JSON JSON HTML GET API POST API JSON, HTML 管理画面 ※簡略化したもの、実際とは異なる箇所があります
18. フロントの表示・操作はsnapshotテスト＋実際のtiptapクライアントで 品質 18 #prtimes_editor • vitestのsnapshotで表示の確認（テスト用のレンダー関数を用意） ◦ toMatchSnapshot()で検証
19. フロントの表示・操作はsnapshotテスト＋実際のtiptapクライアントで 品質 19 #prtimes_editor • testing-libraryでtiptapクライアント（useEditor）を直接使用する • React Hooksにtiptapのロジックを集約する • mockの手間を省ける、実際のクライアントで 同期できるので信頼性が上がる • デメリット：テスト実行時間増
20. 品質 20 #prtimes_editor 管理画面 backend コンテンツAPI DynamoDB JSON JSON HTML GET API POST API JSON, HTML 管理画面 ※簡略化したもの、実際とは異なる箇所があります
21. ユーザー操作のテストはE2Eで検証 品質 21 #prtimes_editor • Playwrightで実装 • 正常系を担保するように書いている
22. テスト2年間運用してどうだった？ 品質 • 全体的にテスト戦略の見直しが必要だと感じています。 • 課題：ユニットテスト時間の増加 • E2Eテストで担保できるケースが多いので、tiptapクラアントを使ったテストは削 減・移行しています。 • バックエンドと同様に入出力（HTML→JSON）のアウトプットを検証するテスト を追加しています。 • バックエンド ◦ カバレッジを担保するためDynamoDBをdumpしてテストする方法を検討中 22 #prtimes_editor
23. 目次 23 • 設計「技術選定・設計」 • 品質「テスト戦略」 • 使いやすさ「アクセシビリティ」 • 使いやすさ「HTMLにこだわる」 #prtimes_editor
24. アクセシビリティ 使いやすさ • リリースの際にマウス操作が前提になりがちなリッチエディタにおいても、キー ボード操作など、できるようにこだわって作りました。 • Radix UIを採用 ◦ select ◦ popover ◦ modal などを使用してリッチエディタのツールバー を実装 24 #prtimes_editor
25. アクセシビリティ 使いやすさ • エディタ内部のキーボード操作にこだわる ◦ ProseMirrorの `state.selection` でキーボードの状態が取れるので、挙動を カスタムできる ◦ キーボードのbackspaceキーで削除しにくい要素を削除対象にできたりなど を実装 25 #prtimes_editor
26. 2年間運用してどうだった？ 品質 • 削除しにくいなどのフィードバックが減った一方で、意図しない挙動が起きたなど ユーザーによってリッチエディタに求める挙動は異なるという学びがあった。 • スクリーンリーダーのユーザーに実際にリッチエディタを試してもらった ◦ エディタ内の装飾情報やツールの操作方法などを取得できず、満足に使用は できなかった • リッチエディタを完璧にするよりも代替手段を検討するという選択肢 ◦ 同等の機能を要するマークダウンエディタや運用フローでカバーするなど？ ▪ tiptap v3ではマークダウンにレンダーする機能が検討されている 26 #prtimes_editor
27. 目次 27 • 設計「技術選定・設計」 • 品質「テスト戦略」 • 使いやすさ「アクセシビリティ」 • 使いやすさ「HTMLにこだわる」 #prtimes_editor
28. HTMLにこだわる 使いやすさ • (CMSという特性上もありますが)リッチエディタを作る時は徹底的に出力される HTML構造にこだわり、調査をしましょう • 弊社ではリリースの際に、社内のPM、HTML有識者、デザイナーとHTML勉強会 ・ユーザーに配信するHTMLについて議論を重ねました。 ◦ 仕様の明確化につながった ◦ これから追加されるかも知れない機能も明確化（HTML仕様に乗っ取ったも のをリリースしていくことになるので） ▪ 後方互換が壊れにくい、予測しやすい仕様・設計になる 28 #prtimes_editor
29. 2年間運用してどうだった？ 使いやすさ めちゃくちゃ大事な作業だった！！ リッチエディタ作る全人類時間をかける価値はあります！ 29 #prtimes_editor
30. まとめ • テスト戦略はフロントエンド界隈では「テスティングトロフィー」が引用されます が、テスト実行時間・テスト要件を考えて戦略を考えることが大切です。 ◦ 「テストサイズ」という考え方が参考になります。 ◦ tiptapの拡張して使用するという仕組み上、スモール（ユニット）テストも より有効になると感じています • 「HTMLにこだわる」のは時間をかける価値があります。 ◦ 仕様の明確化 ◦ 使いやすさ、アクセシビリティ的にも大きく貢献します。 30 #prtimes_editor
31. 31 #prtimes_editor
32. Thanks :) 32 #prtimes_editor @ryusou_mtkh