blocknote-to-tiptap.md

リッチエディター移行ガイド: BlockNote → TipTap

---

フェーズ別の全体像

フェーズ	目的	主なアウトプット
① 現状把握	BlockNote 導入範囲・保存形式・拡張機能を棚卸	機能パリティ表・既存データスキーマ
② ギャップ分析	TipTap v3 で同等機能を実現する方法を決定（標準 Extension／自作 Extension／不要機能）	代替 Extension 一覧・実装方針
③ PoC	小規模画面で TipTap を組み込み、データ変換方式と UI を検証	検証レポート・変換スクリプト雛形
④ 実装 & 並行運用	BlockNote と TipTap の併存、段階的切替	フラグ制御・リリース手順書
⑤ データ移行	BlockNote JSON を TipTap JSON へ一括変換	移行スクリプト・リハーサル結果
⑥ QA & リリース	回帰試験・パフォーマンステスト	テストレポート・ロールバック手順

---

1. 事前調査ポイント

• 保存形式

  • BlockNote: JSON形式がロスレス。Markdownは一部欠損。
  • TipTap: ProseMirror JSONがネイティブで、HTML/Markdownの相互変換が可能。

• リアルタイム協働

  • 両者とも ProseMirror ベースのため、Convex / Hocuspocus などで共通実装が可能。

---

2. 実装ステップ

2‑1. コンポーネント置換

// BlockNote（旧）
<BlockNoteView onChange={save} initialContent={json} />

// TipTap（新）
<EditorContent editor={editor} />
// editor = new Editor({ content: json, ... })

• BlockNote のテーマや UI は TipTap ではそのまま使えないため、スタイルの再設計が必要。

---

2‑2. データ変換方針

方式	手順	長所	短所
オンライン変換	JSON → Markdown → setContent(markdown)	即時反映可能	ロード遅延／情報欠損リスク
バッチ変換	JSON → HTML → generateJSON(html) → DB保存	損失最小、安定表示	マイグレーション作業が必要

---

2‑3. TipTap拡張機能マッピング（例）

BlockNote 機能	TipTap Extension	備考
Callout	@tiptap/extension-callout	独自アイコンは要カスタマイズ
AI コマンド	command-menu + API呼び出し	UX要再現
Slash Commands	slash-command 拡張	補完・履歴対応必要
協働カーソル	collaboration-cursor	Convex/Hocuspocusと併用可能

---

3. テスト戦略

テスト領域	目的	方法
表示差分	レイアウト破綻の検出	Puppeteer + pixelmatch
入力互換性	IME／スクリーンリーダ	Cypress + AxeCore
データ変換整合性	JSON→HTML→JSON の一致	Jestでラウンドトリップテスト
コラボ編集	同時編集・Undo/Redo動作	多ブラウザ検証
パフォーマンス	レンダリング速度	Web Vitals（INP, CLSなど）

---

4. 主な懸念点と対策

懸念	内容	対策
情報損失	Markdown変換で色や並びが落ちる	HTMLベースで変換／差分テスト導入
UI変化	Block風UIと違うUX	ツールチップや導線で補完／段階移行
商用ライセンス	TipTap Proは有償	OSS代替調査／見積もり取得
バンドル肥大	多機能化によるJS肥大	Dynamic Import + tree-shaking
アクセシビリティ	ARIAなど自前実装要	WCAG準拠チェック／自動監査
協働衝突	BlockNote特有CRDTとの非互換	OT統一／Feature Flagで切替制御
ロールバック困難	データ形式が後方互換でない	JSONバージョン列保持／双方向変換残置

---

5. 移行ロードマップ（例：3か月）

期間	タスク
1–2週目	機能棚卸・PoC
3–4週目	Extension調整・変換スクリプト実装
5–6週目	並行運用開始・自動テスト整備
7–8週目	バッチ移行リハーサル・負荷試験
9–10週目	本番移行（Feature Flag切替）
11–12週目	フィードバック反映・旧コード削除

---

まとめ

• BlockNoteとTipTapは同じProseMirrorベースのため、内部構造は互換性が高い。
• 最大の課題は保存形式とUXの違いによる変換精度とユーザー混乱。
• TipTap v3のエコシステムを活かすことで、長期的には保守性・拡張性が向上。

段階的な検証とテストを前提に、堅実な移行が可能です。