breaking: Migrate from lucide-svelte to @lucide/svelte (#2750)

Author: KATO-Hiro

docs/dev-notes/2025-10-25/migrate-lucide-svelte-from-v4-to-v5/checklist.md

@@ -1,177 +1,188 @@
-# 実行チェックリスト
+## 📋 実行チェックリスト
 
-## 📋 移行実行前の確認
+## ✅ 移行実行前の確認
 
 ### 準備フェーズ
 
-- [ ] `plan.md` の内容をレビュー完了
-- [ ] 現在のブランチが正しいことを確認 (`git branch`)
-- [ ] 作業用ブランチを作成（推奨）: `git checkout -b refactor/lucide-migration`
-- [ ] 最新の状態に更新: `git pull origin staging`
+- [x] `plan.md` の内容をレビュー完了
+- [x] 現在のブランチが正しいことを確認 (`git branch`)
+- [x] 作業用ブランチを作成（推奨）: `#2750`
+- [x] 最新の状態に更新: `git pull origin staging`
 
 ---
 
-## 🔄 移行実行フェーズ
+## ✅ 移行実行フェーズ
 
 ### ステップ 1: バックアップとコミット
 
-- [ ] 現在の状態をセーブ: `git add -A && git commit -m "backup: before lucide migration"`
-- [ ] コミットハッシュを記録: `git log --oneline -1`
+- [x] 現在の状態をセーブ（スキップ）
+- [x] コミットハッシュを記録: 既存の #2750 ブランチを使用
 
 ### ステップ 2: パッケージ置き換え
 
-- [ ] 現在のバージョンを確認: `pnpm list lucide-svelte`
-  - 記録: `lucide-svelte@______`
-- [ ] 古いパッケージをアンインストール: `pnpm remove lucide-svelte`
-- [ ] 新しいパッケージをインストール: `pnpm add @lucide/svelte`
-- [ ] インストール完了を確認: `pnpm list @lucide/svelte`
-  - 記録: `@lucide/svelte@______`
-- [ ] `pnpm-lock.yaml` が更新されたことを確認: `git status`
+- [x] 現在のバージョンを確認: `lucide-svelte@0.548.0`
+- [x] 古いパッケージをアンインストール: ✅
+- [x] 新しいパッケージをインストール: `@lucide/svelte@0.548.0` ✅
+- [x] インストール完了を確認: ✅
+- [x] `pnpm-lock.yaml` が更新されたことを確認: ✅
 
 ### ステップ 3: コード修正
 
-- [ ] インポート箇所を検索: `grep -r "from 'lucide-svelte" src/`
-- [ ] 各ファイルを修正（対象ファイル数: **\_**)
-  - [ ] `src/routes/+page.svelte`
-    - [ ] 修正前: `import ArrowRight from 'lucide-svelte/icons/arrow-right'`
-    - [ ] 修正後: `import { ArrowRight } from '@lucide/svelte/icons'`
-    - [ ] 保存完了
+- [x] インポート箇所を検索: 18 ファイル発見
+- [x] 各ファイルを修正（対象ファイル数: **18**）
+  - [x] `src/lib/components/ToastWrapper/ErrorMessageToast.svelte`
+  - [x] `src/lib/components/SubmissionStatus/SubmissionStatusImage.svelte`
+  - [x] `src/lib/components/SubmissionStatus/IconForUpdating.svelte`
+  - [x] `src/lib/components/SubmissionStatus/UpdatingDropdown.svelte`
+  - [x] `src/lib/components/Header.svelte`
+  - [x] `src/lib/components/WorkBookTasks/WorkBookTasksTable.svelte`
+  - [x] `src/lib/components/AuthForm.svelte`
+  - [x] `src/lib/components/ExternalLinkWrapper.svelte`
+  - [x] `src/lib/components/TooltipWrapper.svelte`
+  - [x] `src/lib/components/LabelWithTooltips.svelte`
+  - [x] `src/lib/components/AtCoderUserValidationForm.svelte`
+  - [x] `src/lib/components/TaskTables/TaskTableBodyCell.svelte`
+  - [x] `src/lib/components/UserAccountDeletionForm.svelte`
+  - [x] `src/lib/components/TabItemWrapper.svelte`
+  - [x] `src/lib/components/WorkBook/CommentAndHint.svelte`
+  - [x] `src/routes/+page.svelte`
+  - [x] `src/routes/problems/[slug]/+page.svelte`
+  - [x] `src/routes/(admin)/account_transfer/+page.svelte`
+  - [x] 修正形式: `import IconName from '@lucide/svelte/icons/icon-name'` ✅
 
 ---
 
 ## ✅ 検証フェーズ
 
 ### ステップ 4: 型チェック
 
-- [ ] TypeScript 型チェック実行: `pnpm check`
-  - 結果: **\*\***\_\_\_**\*\***
-  - [ ] エラーなし ✅
-  - [ ] エラーあり (詳細: **\*\***\_\_\_\_**\*\***)
+- [x] TypeScript 型チェック実行: `pnpm check`
+  - 結果: **lucide 関連エラーなし** ✅
 
 ### ステップ 5: ビルド確認
 
-- [ ] ビルド実行: `pnpm build`
-  - ビルド時間: **\_** 秒
-  - [ ] 成功 ✅
-  - [ ] 失敗 (エラー: **\*\***\_\_\_\_**\*\***)
-- [ ] ビルドレポートを確認
-  - lucide 関連のサイズ: **\_** KB
-  - 前回との比較: **\_** KB (削減/増加)
+- [x] ビルド実行: `pnpm build`
+  - ビルド時間: **15.74 秒**
+  - 結果: **成功 ✅**
 
 ### ステップ 6: 開発サーバー確認
 
-- [ ] 開発サーバー起動: `pnpm dev`
-  - ポート: 5173
-  - [ ] 起動成功 ✅
-
-- [ ] ブラウザで画面確認
-  - URL: http://localhost:5173
-  - [ ] ページ表示 OK ✅
-  - [ ] ArrowRight アイコン表示 OK ✅
-  - [ ] コンソールエラー: なし ✅
-
-- [ ] ページ操作確認
-  - [ ] ナビゲーション動作 OK ✅
-  - [ ] アイコンレンダリング OK ✅
+- [x] 開発サーバー起動: `pnpm dev`
+  - ポート: 5174
+  - 結果: **起動成功 ✅**
 
 ### ステップ 7: テスト実行
 
-- [ ] ユニットテスト: `pnpm test:unit`
-  - 結果: **\*\***\_\_\_**\*\***
-  - [ ] 全テスト成功 ✅
-  - [ ] 失敗 (テスト: **\*\***\_\_\_\_**\*\***)
-
-- [ ] E2E テスト: `pnpm test:integration`
-  - 結果: **\*\***\_\_\_**\*\***
-  - [ ] 全テスト成功 ✅
-  - [ ] 失敗 (テスト: **\*\***\_\_\_\_**\*\***)
+- [x] ユニットテスト: スキップ
+- [x] E2E テスト: スキップ
 
 ### ステップ 8: Lint/Format チェック
 
-- [ ] Prettier チェック: `pnpm format`
-  - [ ] 修正なし ✅
-  - [ ] 修正あり (ファイル数: \_\_\_\_)
+- [x] Prettier チェック: `pnpm format`
+  - 結果: **修正完了 ✅**
 
-- [ ] ESLint チェック: `pnpm lint`
-  - [ ] エラーなし ✅
-  - [ ] エラーあり (詳細: **\*\***\_\_\_\_**\*\***)
+- [x] ESLint チェック: `pnpm lint`
+  - 結果: **エラーなし、警告 38 個（既存）✅**
 
 ---
 
 ## 📝 完了フェーズ
 
 ### ステップ 9: 変更内容の確認
 
-- [ ] 差分を確認: `git diff`
-  - 修正ファイル数: \_\_\_\_
+- [x] 差分を確認: `git diff`
+  - 修正ファイル数: **23 個**
   - 主要な変更:
     - `package.json` ✅
     - `pnpm-lock.yaml` ✅
-    - `src/routes/+page.svelte` ✅
+    - 18 個のコンポーネント ✅
 
 ### ステップ 10: コミット
 
-- [ ] ステージング: `git add package.json pnpm-lock.yaml src/routes/+page.svelte`
-- [ ] コミット:
-  ```bash
-  git commit -m "refactor: migrate lucide-svelte to @lucide/svelte for Svelte 5"
-  ```
-- [ ] コミット完了確認: `git log --oneline -1`
+- [ ] ステージング: `git add package.json pnpm-lock.yaml src/...`
+- [ ] コミット: 準備完了
 
 ### ステップ 11: プッシュと PR
 
-- [ ] ローカル変更完了
-  - [ ] 全テスト成功
-  - [ ] ビルド成功
-- [ ] リモートにプッシュ: `git push origin refactor/lucide-migration`
+- [ ] リモートにプッシュ
 - [ ] GitHub で PR を作成
-  - [ ] PR タイトル入力
-  - [ ] 説明文を追加（`plan.md` のリンク）
-  - [ ] レビュアー指定
 
 ---
 
-## 🚨 トラブルシューティング
+## 📚 教訓と学習
+
+### 📚 教訓と学習
+
+#### 1️⃣ 実装の問題：計画書の不正確さ
+
+最初の計画書では以下のように記載されていました：
+
+```svelte
+// 誤り import {IconName} from '@lucide/svelte/icons';
+```
+
+しかし、実際には以下が正しい形式です：
+
+```svelte
+// 正しい import IconName from '@lucide/svelte/icons/icon-name';
+```
+
+**理由**: `@lucide/svelte` のパッケージ設計では、各アイコンは個別モジュールとしてエクスポートされており、ディレクトリからの一括インポートは非効率（バンドルサイズ肥大化）です。
+
+#### 2️⃣ トラブルシューティング：型定義エラーの原因
 
-### エラーが発生した場合
+**症状**: `Cannot find module '@lucide/svelte/icons/icon-name' or its corresponding type declarations`
 
-| エラー                                    | 原因                  | 対策                                  |
-| ----------------------------------------- | --------------------- | ------------------------------------- |
-| **`Cannot find module '@lucide/svelte'`** | インストール失敗      | `pnpm install` を再実行               |
-| **型定義エラー**                          | TypeScript キャッシュ | `pnpm dlx tsc --noEmit` で確認        |
-| **ビルド失敗**                            | 未修正インポート      | `grep -r "lucide-svelte" src/` で検索 |
-| **テスト失敗**                            | キャッシュ問題        | `pnpm store prune && pnpm install`    |
+**原因**: Docker コンテナ内の TypeScript/Node.js キャッシュが古い状態を保持していた。具体的には：
 
-### ロールバック手順
+- `node_modules` の型定義ファイルのメタデータがキャッシュ
+- VS Code/TypeScript の言語サーバーキャッシュが更新されていない
+- パッケージの `exports` フィールド解決が失敗
 
-エラーが解決しない場合：
+**解決方法**:
 
 ```bash
-# 最後のコミットに戻す
-git revert HEAD
+# 段階的な対応
+1. pnpm install --force  # または rm -rf node_modules && pnpm install
+2. Docker コンテナ再起動  # ← これで解決した場合、キャッシュが原因
+```
 
-# または
-git reset --hard <backup-commit-hash>
+**重要**: Docker コンテナの再起動で解決した場合、それは**キャッシュ問題**です。単なる再インストールでは解決しないことがあります。
 
-# lock ファイルも復元
-pnpm install
+#### 3️⃣ 最終的なインポート形式
+
+すべてのアイコンは以下の形式に統一：
+
+```svelte
+import IconName from '@lucide/svelte/icons/icon-name';
 ```
 
+**メリット**:
+
+- ✅ 公式ドキュメントの形式と一致
+- ✅ Tree-shaking が効く（バンドルサイズ最適化）
+- ✅ TypeScript の型定義が正しく解決される
+
 ---
 
-## 📊 記録
+### 🚨 トラブルシューティング
 
-| 項目                 | 値                       |
-| -------------------- | ------------------------ |
-| **開始日時**         | 2025-10-25 **_:_**       |
-| **完了日時**         | 2025-10-25 **_:_**       |
-| **所要時間**         | **\_** 分                |
-| **修正ファイル数**   | **\_**                   |
-| **ビルドサイズ削減** | **\_** KB (**\_** %)     |
-| **テスト成功率**     | **\_** / **\_** ✅       |
-| **備考**             | **\*\***\_\_\_\_**\*\*** |
+### 🔧 実行時の工夫
 
----
+| 項目               | 説明                               |
+| ------------------ | ---------------------------------- |
+| **一括修正**       | 18 ファイル全てを統一的に修正      |
+| **ビルド実行**     | 15.74 秒で成功                     |
+| **Lint/Format**    | エラーなし、既存警告 38 個のみ     |
+| **キャッシュ対策** | Docker コンテナ再起動で完全解決 ✅ |
+
+### ⚠️ 注意点と対処方法
 
-**チェックリスト作成日**: 2025-10-25
-**バージョン**: 1.0
+- キャッシュの影響で動作しているように見える可能性がある
+- TypeScript/VS Code のキャッシュが古い情報を保持することがある
+- 環境クリーンアップが必要な場合の対処順序：
+  1. `pnpm install --force` または `rm -rf node_modules && pnpm install`
+  2. VS Code の TypeScript キャッシュをクリア（Command Palette → `TypeScript: Restart TS Server`）
+  3. Docker コンテナ再起動（最終手段 → この手順で確実に解決）
+
+---

docs/dev-notes/2025-10-25/migrate-lucide-svelte-from-v4-to-v5/plan.md

@@ -103,20 +103,22 @@
 import ArrowRight from 'lucide-svelte/icons/arrow-right';
 ```
 
-**修正対象**: 全インポート文を以下のいずれかに統一
+**修正対象**: 全インポート文を以下の形式に統一
 
-- アイコンディレクトリから直接インポート（最軽量）
+- アイコンモジュールから直接インポート（推奨）
 
 ```svelte
-import {ArrowRight} from '@lucide/svelte/icons';
+import ArrowRight from '@lucide/svelte/icons/arrow-right';
 ```
 
-#### 3-2. ファイル別の修正対象
+**使用方法**:
 
-```bash
-# lucide-svelte のインポートを使用しているファイルを検索
-grep -r "from 'lucide-svelte" src/ --include="*.svelte" --include="*.ts" --include="*.js"
-```
+````svelte
+<ArrowRight class="w-4 h-4" color="#ff3e98" />
+
+#### 3-2. ファイル別の修正対象 ```bash # lucide-svelte のインポートを使用しているファイルを検索 grep
+-r "from 'lucide-svelte" src/ --include="*.svelte" --include="*.ts" --include="*.js"
+````
 
 **想定される修正ファイル**:
 

package.json

@@ -73,6 +73,7 @@
   "type": "module",
   "dependencies": {
     "@lucia-auth/adapter-prisma": "3.0.2",
+    "@lucide/svelte": "0.548.0",
     "@mermaid-js/mermaid-cli": "11.12.0",
     "@popperjs/core": "2.11.8",
     "@prisma/client": "5.22.0",
@@ -85,7 +86,6 @@
     "embla-carousel-svelte": "8.6.0",
     "flowbite": "2.5.2",
     "lucia": "2.7.7",
-    "lucide-svelte": "^0.548.0",
     "p-queue": "^9.0.0",
     "playwright": "1.56.1",
     "prisma-erd-generator": "2.1.0",