taiga-ui-migration

目標

Taiga UI プロジェクトを次のメジャーバージョンへ正常に移行します。その際、以下を実現します。

• 実行時の動作、テンプレートの出力、スタイル、ビルドツールを維持する
• スキーマティクス実行後の TODO に安全かつ体系的に対応する
• よくある移行時の問題を特定して解決する
• 慎重な検証により、破壊的変更を最小限に抑える

ステップ 0：作業前に状況を確認する

重要： コマンドを実行したりファイルを編集したりする前に、以下を収集して確認してください。

質問	確認場所
移行元と移行先のメジャーバージョン	明記されていない場合はユーザーに確認する
パッケージマネージャー（npm / yarn / pnpm）	package.json の packageManager フィールド、またはロックファイルの有無
ビルドシステム（Angular CLI / Nx）	nx.json または angular.json の有無
モノレポ：影響を受けるアプリ／ライブラリの数	nx.json の projects、または angular.json の projects
カスタム webpack / ESBuild 設定	angular.json の builder フィールド

Taiga UI MCP サーバーを利用できる場合は、 作業に進む前に get_migration_guide を使って、 {CURRENT_MAJOR} → {NEXT_MAJOR} の移行ノートを読み込んでください。これにより、 セッション全体を通じて信頼できる破壊的変更の情報を参照できます。

表のすべての項目が解決するまで、フェーズ 1 に進まないでください。

作業を始める前に - 前提条件チェックリスト

• Node.js：Node.js LTS バージョンを使用する
• NPM：バージョン 10 以降（または yarn / pnpm の同等バージョン）
• 現在の Taiga UI：まず v{CURRENT_MAJOR} の最新バージョンに更新する
• Angular：v{NEXT_MAJOR} と互換性のあるバージョンに更新する（移行ガイドを確認）
• Prettier：移行後の改行コードの問題を防ぐため、endOfLine オプションを auto に設定する

⛔ --legacy-peer-deps、--force、または依存関係の解決を回避するフラグは絶対に使用しないでください。 これらのフラグは、実行時に問題を引き起こす実際のバージョン競合を隠してしまいます。競合は明示的に解決してください。

移行ワークフロー

フェーズ 1：移行スキーマティクスを実行する

Angular CLI プロジェクトの場合：

ng update @taiga-ui/cdk

Nx プロジェクトの場合：

nx migrate @taiga-ui/cdk
nx migrate --run-migrations=migrations.json

フェーズ 2：変更されたコードを確認する

スキーマティクスの実行後：

1. 変更されたコード行をすべて確認する - 一部の変更には、新しいコードコメント（// TODO: (Taiga UI migration) など）が含まれています。これらのコメントには通常、削除されたエンティティを新しい代替手段に手動で移行する手順が記載されています。

2. @taiga-ui/legacy のインポートを確認する - @taiga-ui/legacy からの新しいインポートが見つかることがあります。これは、古いエンティティが完全に削除されるまでの移行用パッケージです。

   • v{NEXT_MAJOR} のこのパッケージに含まれるすべてのものは、v{NEXT_MAJOR+1} で削除されます
   • 一時的に使い続けることはできます
   • 非推奨となったエンティティの多くには、@deprecated タグが付いた最新の代替手段があります（IDE では取り消し線付きで表示されます）
   • 強く推奨：できるだけ早く最新の代替手段に置き換えてください

フェーズ 3：移行 TODO に対応する

実行時の動作、テンプレートの出力、スタイル、ビルドツールを損なうことなく、スキーマティクス実行後の TODO に対応します。

TODO 対応の基本ルール

• TODO は推測してよいという許可ではありません。実際に安全に変更できるものを確認するための指針です。
• 対象範囲内の対応可能な TODO はすべて修正します。ただし、各修正の安全性を、周辺コードと使用状況から確認してから行ってください。
• 現在の動作を維持できる、可能な限り小さな変更を優先してください。
• TODO に削除するよう書かれているというだけで、非推奨のパッケージ、インポート、ユーティリティを削除しないでください。コードベース上で未使用だと確認できた場合に限り、削除してください。
• ロジック、生成されるマークアップ、CSS の適用、またはスクリプトの動作が変わる可能性がある場合は、修正する前に周辺の使用状況を検証してください。
• 安全な修正方法が明らかでない場合は、コードを独自に作り出さず、ユーザーに確認してください。

TODO の処理順序

共有モジュールとバレルファイル（index.ts、public-api.ts）から TODO を処理して、利用側の作業を進められるようにします。その後、サービス、コンポーネント、最後にスタイルのエントリーポイントへ進みます。次のファイルに移る前に、1 つのファイル内の TODO をすべて完了させてください。完了できないファイルがある場合は、MIGRATION_ISSUES.md に Quick Entry を追加してから続行します。

TODO の分類 → 必須の質問テンプレート

カテゴリ	中断条件	質問する内容
テンプレート／DI（優先度高）	直接置き換えられるものがある	通常は確認せずに安全に修正できます
スタイルパッケージの削除	そのパッケージのクラスがテンプレート内にある	「<file> で <className> が使われています。これらを移行するまで、古いスタイルパッケージを残すべきですか？」
直接の置き換えがない	TODO にその旨が明記されている	「移行メモによると、<API> は直接の置き換えがないまま削除されました。どのような動作に置き換えるべきですか？」
動的バインディング	実行時の値を使う [input]="expr"	「バインディング [appearance]="mode" は実行時の値を使います。新しい API でも同じ値を受け入れるべきですか？」
有効な方法が複数ある	ドキュメントに複数の置き換え方法がある	「置き換え方法が 2 つあります。<A> と <B> のどちらが意図した動作に合っていますか？」
警告のみ	TODO で手動の判断が必要と示されている	「この TODO には判断が必要です：<TODO text>。どのような方法を希望しますか？」

分類例：

• TODO: replace TuiButtonModule with TuiButton → テンプレート／DI（優先度高、通常は安全に修正できます）
• TODO: remove @taiga-ui/styles import → スタイルパッケージ（中断し、まず使用状況を確認します）
• TODO: migrate to standalone component API → TypeScript（優先度中、利用側を確認します）
• TODO: this API was removed, no direct replacement → 警告のみ（ユーザーに確認します）

TODO のワークフロー

1. 上の表を使って TODO を特定し、分類します
2. MCP を使用して置き換え方法を調べます（利用可能な場合）：
   • コンポーネントの置き換えでは、新しいコンポーネント名を指定して get_component_example を呼び出します
   • アーキテクチャの変更では、get_overview または migration_guide を呼び出します
   • ローカルコードの文脈だけで置き換え方法が明確な場合に限り、この手順を省略します
3. 編集する前に実際の使用箇所を追跡します：
   • 現在のコンポーネント、テンプレート、スタイル、周辺ファイルを検索して、直接参照されている箇所を確認します
   • スタイル関連の TODO では、後述の「スタイルパッケージ削除」アルゴリズムに従います
   • TODO が 1 つの箇所を対象としているのか、より広いパターンを対象としているのかを確認します
4. TODO に安全に対処できるか判断します：
   • 1 対 1 で置き換えられ、動作が維持される場合は適用します
   • 非推奨パッケージに関する記述がある場合は、削除する前に、実行時、テンプレート、スタイルのいずれかでまだ依存している箇所がないか確認します
   • 置き換え方法が複数考えられる場合や、修正が動的バインディングまたは生成された出力に依存する場合は、中断して質問テンプレートを使ってユーザーに確認します
5. 安全にできる最小限の修正を適用します：
   • 変更箇所を限定します
   • 動作を維持するために必要な場合を除き、大規模なリファクタリングは避けます
   • 周辺の根拠から削除が妥当だと判断できない限り、インポート、パッケージ、スクリプトを削除しません
6. 結果を検証します：
   • 変更箇所を読み直し、ロジック、クラス、セレクターの整合性を確認します
   • 可能であれば、影響範囲に対して利用可能な最小限のチェックを実行します
   • 検証後も変更が曖昧に感じられる場合は、修正範囲を広げずにユーザーへ確認します

フェーズ 4：トラブルシューティング

問題：TypeScript エラー TS6133 — 変数が宣言されていますが、値が読み取られていません

解決策： 移行スケマティクには、意図的にコードのフォーマット処理が含まれていません（実行が遅くなるためです）。IDE またはリンターを使用してください。

• WebStorm：ルートフォルダーを右クリック →「Optimize imports」（未使用のインポートをすべて再帰的に削除します）
• Visual Studio Code：すべてのファイルを対象に、フォルダーのソースアクション「Organize Imports」を再帰的に実行します
• ESLint/Prettier：適切に最適化されたルールを実行し、未使用のインポートを整理します

問題：Yarn ユーザー、または legacy-peer-deps による回避策が必要な場合

解決策： Taiga UI は多くの Taiga Family パッケージに依存しています。Yarn と pnpm は、推移的なピア依存関係を自動的にはインストールしません。各 Taiga UI パッケージの package.json を確認し、不足しているピア依存関係を手動でインストールしてください。

問題：ng-web-apis、maskito、ng-polymorpheus、または ng-event-plugins の依存関係を解決できない場合

解決策： 上記と同様に、各 Taiga UI パッケージの package.json を確認し、推移的なピア依存関係を手動でインストールしてください。

問題：nx migrate --run-migrations の実行後に Cannot find module 'ts-morph' エラーが発生する場合

解決策： これは ng migrate コマンドに関する Nx の問題です。次のいずれかを実行してください。

• Nx のバージョンを上げる、または
• npm install を実行してから、移行を再実行する

問題：FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

解決策： 移行スケマティクはすべてのファイルとディレクトリを再帰的に走査するため、メモリを大量に消費する場合があります。Node.js プロセスのメモリ上限を増やしてください。

NODE_OPTIONS="--max-old-space-size=4096" ng update @taiga-ui/cdk

問題：基本的な ng update / nx migrate コマンドが失敗し、スケマティクを手動で実行する必要がある場合

解決策：

1. package.json のすべての Taiga UI パッケージを手動で v{NEXT_MAJOR} に更新します（コンソールコマンドを使わずにバージョンを変更してから、npm install を実行します）
2. node_modules/@taiga-ui/cdk/package.json に v{NEXT_MAJOR} のバージョンが含まれていることを確認します
3. 次を実行します。

Angular CLI：

ng update @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version> --to=@taiga-ui/cdk@<new-version>

Nx：

nx migrate @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version>
nx migrate --run-migrations=migrations.json

不確かな移行箇所や問題のある移行箇所の記録

すぐには解決できない移行の問題に遭遇した場合は、不確かな箇所や問題の可能性がある箇所をすべて追跡できるよう、専用のファイル（例：MIGRATION_ISSUES.md または TODO_MIGRATION.md）を作成し、維持してください。

2 段階のドキュメント形式

簡易エントリー（単純なブロッカー向け）：

- [ ] `src/app/button.component.html:34` — `TuiButtonModule` TODO,
      blocked: dynamic `[appearance]` binding, need user input

次の場合は簡易エントリーを使用してください。

• ブロックの理由が明確な単一ファイルの問題
• TODO を見れば、尋ねるべき内容が明らかな場合
• ユーザーの判断が必要な、軽微なスタイルパッケージの使用

詳細エントリー（複数のファイルに影響する場合、または動作変更の可能性がある場合のみ）：

次の場合は、以下の 7 項目形式を使用してください。

• 複数のファイルにまたがる問題
• 動作変更の可能性がある場合
• 複雑なスタイルパッケージの依存関係
• 詳細な説明が必要な場合

詳細エントリーの必須形式

記録する問題ごとに、次の内容を含めてください。

1. ファイルパス — 影響を受けるファイルの相対パス全体（またはファイルの一覧）
2. 行番号 — 問題が発生している正確な行
3. 元のコード — 修正を試みる前のコードスニペット
4. 問題の説明 — 不確かな点や問題のある点を明確に説明します
5. 試した解決策 — 検討した移行方法と、それらがうまくいかない可能性がある理由
6. 影響の可能性 — 間違った修正を適用した場合に壊れる可能性があるもの（ランタイム、テンプレート、スタイル、ビルド）
7. 移行バージョン — 該当する Taiga UI の移行バージョン（判明している場合）

詳細エントリーの形式例

## Issue #<number>: <Brief description>

**Files:**

- `path/to/component.ts`
- `path/to/component.html`

**Lines:** 42, 15

**Migration:** v4 -> v5

**Original code:**

```typescript
// TODO: migrate to new button API
@Input() mode: 'accent' | 'primary' = 'primary';
```

```html
<button [mode]="mode">Click me</button>
```

**Issue:**
The old `mode` input was replaced with a new directive-based API, but this component
uses dynamic binding that may not be compatible with the new approach.

**Attempted solutions:**

- Direct replacement with `tuiAppearance` - unclear if dynamic values work
- Keeping old API temporarily - requires deprecated module import

**Potential impact:**

- Runtime error if binding fails
- Visual regression if styling is not applied correctly

ワークフローへの組み込み

1. 初回スキャン中： 移行セッションの開始時に移行問題ファイルを作成します
2. 行き詰まったとき： 次の TODO に進む前に、簡易エントリーを追加します
3. ユーザーに質問する前： 質問の中で、記録したエントリーを参照します
4. 解決後： 適用した修正について簡潔なメモを添えて、エントリーを解決済みとしてマークします

完了の定義

次のすべてが満たされたとき、移行セッションは完了です。

• ソースファイルに // TODO: (Taiga UI migration) コメントが残っていない、または残っている各 TODO に対応する項目が MIGRATION_ISSUES.md に記載されている
• @taiga-ui/legacy からのインポートが存在しない、または残っている各インポートがユーザーによって明示的に承認されている
• ng build / nx build がエラーなしで完了する
• 新たな TypeScript エラーが発生していない（未使用インポートの TS6133 エラーは許容されます。フェーズ 4 の説明に従って IDE で解決してください）
• MIGRATION_ISSUES.md のすべての項目をユーザーに提示している

移行に必要な範囲を超えて、コードのリファクタリング、名前の変更、改善を行わないでください。

ユーザーに確認するタイミング

TODO に関するすべての判断には、TODO の分類表にある質問テンプレートを使用してください。

さらに、次の場合は確認してください。

• 移行スキーマティクスが失敗した、または予期しないエラーが発生した
• プロジェクトに移行へ影響する可能性のあるカスタム設定がある
• ステップ 0 のコンテキストを自動的に特定できない
• Taiga UI パッケージのバージョンをそろえても、ピア依存関係の競合を解決できない

行ってはいけないこと

• 依存関係の解決を回避する --legacy-peer-deps、--force、その他のフラグを使用しないでください。また、.npmrc にすでに記載されていない場合は、legacy-peer-deps=true を追加しないでください — これらは移行後の実行時に問題を引き起こす実際のバージョン競合を隠してしまいます。代わりに、競合を明示的に解決してください
• TODO のテキストだけを根拠に、修正をハードコードしないでください
• まず非推奨の依存関係を削除して、後から問題を見つけることのないようにしてください
• 移行の TODO に対応する過程で、無関係なコードを書き換えないでください
• 実際の修正方法がすでにわかっていて安全である場合、新たな警告で TODO を抑制しないでください
• ローカルのコードのコンテキストに基づいて変更が安全である理由を説明できない場合は、作業を続けないでください
• 前提条件のチェックリストを省略せず、環境が適切に準備されていることを確認してください
• ステップ 0（コンテキストの収集）を省略せず、作業を始める前に環境を把握してください