Back to Details

taiga-ui-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Goal

目标

Successfully migrate a Taiga UI project to the next major version while:
  • Preserving runtime behavior, template output, styles, and build tooling
  • Handling post-schematics TODOs safely and systematically
  • Identifying and resolving common migration issues
  • Minimizing breaking changes through careful verification
成功将 Taiga UI 项目迁移到下一个大版本，同时：
  • 保留运行时行为、模板输出、样式和构建工具
  • 安全、系统地处理 schematics 执行后的 TODO
  • 识别并解决常见迁移问题
  • 通过谨慎验证将破坏性更改降至最少

Step 0: Gather Context Before Acting

步骤 0：行动前收集上下文

CRITICAL: Before executing any command or editing any file, collect and confirm the following:
QuestionWhere to find it
Source and target major versionsAsk the user if not stated
Package manager (npm / yarn / pnpm)
package.json
→ 
packageManager
field or lock-file presence
Build system (Angular CLI / Nx)Presence of 
nx.json
or 
angular.json
Monorepo: how many apps/libs affected
nx.json
→ 
projects
, or 
angular.json
→ 
projects
Custom webpack / ESBuild config
angular.json
→ 
builder
field
If the Taiga UI MCP server is available, use 
get_migration_guide
now to load the {CURRENT_MAJOR} → {NEXT_MAJOR} migration notes before proceeding. This gives you authoritative breaking-change information for the entire session.
Do not proceed to Phase 1 until every item in the table is resolved.
关键： 在执行任何命令或编辑任何文件前，收集并确认以下内容：
问题获取位置
源版本和目标大版本如果未说明，则询问用户
包管理器（npm / Yarn / pnpm）
package.json
→ 
packageManager
字段或 lock file 是否存在
构建系统（Angular CLI / Nx）是否存在 
nx.json
或 
angular.json
Monorepo：受影响的 apps/libs 数量
nx.json
→ 
projects
，或 
angular.json
→ 
projects
自定义 webpack / ESBuild 配置
angular.json
→ 
builder
字段
如果 Taiga UI MCP server 可用，现在使用 
get_migration_guide
加载 {CURRENT_MAJOR} → {NEXT_MAJOR} 的迁移说明，然后继续操作。这将提供整个会话期间权威的 breaking-change 信息。
在表中的每一项都得到解决之前，不要进入阶段 1。

Before You Start - Prerequisites Checklist

开始前——先决条件检查清单

  • Node.js: Use Node.js LTS version
  • NPM: Version 10 or higher (or equivalent for yarn/pnpm)
  • Current Taiga UI: Update to the latest version of v{CURRENT_MAJOR} first
  • Angular: Update to a version compatible with v{NEXT_MAJOR} (check migration guide)
  • Prettier: Set 
    endOfLine
    option to 
    auto
    to prevent line ending issues after migration
⛔ NEVER use 
--legacy-peer-deps
, 
--force
, or any flag that bypasses dependency resolution. These flags hide real version conflicts that will break at runtime. Resolve conflicts explicitly instead.
  • 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
，或任何绕过依赖解析的标志。 这些标志会隐藏真正的版本冲突，而这些冲突会在运行时导致故障。应显式解决冲突。

Migration Workflow

迁移工作流

Phase 1: Run Migration Schematics

阶段 1：运行迁移 schematics

For Angular CLI projects:
bash
ng update @taiga-ui/cdk
For Nx projects:
bash
nx migrate @taiga-ui/cdk
nx migrate --run-migrations=migrations.json
对于 Angular CLI 项目：
bash
ng update @taiga-ui/cdk
对于 Nx 项目：
bash
nx migrate @taiga-ui/cdk
nx migrate --run-migrations=migrations.json

Phase 2: Review Changed Code

阶段 2：审查变更后的代码

After schematics complete:
  1. Review all changed code lines - Some changes contain new code comments (like 
    // TODO: (Taiga UI migration)
    ). These comments typically contain instructions for manually migrating deleted entities with new alternatives.
  2. Check for @taiga-ui/legacy imports - You may find new imports from 
    @taiga-ui/legacy
    . This is a transitional package for outdated entities before their full removal:
    • Everything in this package in v{NEXT_MAJOR} will be removed in v{NEXT_MAJOR+1}
    • You can continue using them temporarily
    • Most deprecated entities have modern alternatives marked with 
      @deprecated
      tag (IDEs display these as stricken-through)
    • Strongly recommended: Replace with modern alternatives as soon as possible
schematics 完成后：
  1. 审查所有变更的代码行——部分更改会包含新的代码注释（例如 
    // TODO: (Taiga UI migration)
    ）。这些注释通常包含手动迁移已删除实体并使用新替代方案的说明。
  2. 检查 
    @taiga-ui/legacy
    imports    ——你可能会发现来自 
    @taiga-ui/legacy
    的新 imports。这是在相关实体被彻底删除前用于兼容过时实体的过渡性 package：
    • 该 package 中的所有内容都会在 v{NEXT_MAJOR+1} 中从 v{NEXT_MAJOR} 移除
    • 可以暂时继续使用它们
    • 大多数 deprecated 实体都有使用 
      @deprecated
      标签标记的现代替代项（IDE 会将其显示为带删除线）
    • 强烈建议尽快替换为现代替代项

Phase 3: Handle Migration TODOs

阶段 3：处理迁移 TODO

Handle post-schematics TODOs without breaking runtime behavior, template output, styles, or build tooling.
处理 schematics 执行后的 TODO 时，不得破坏运行时行为、模板输出、样式或构建工具。

Core Rules for TODOs

TODO 核心规则

  • TODOs are not permission to guess. They are a prompt to verify what is actually safe to change.
  • Fix all actionable TODOs in scope, but only after proving each fix from nearby code and usage.
  • Prefer the smallest possible change that preserves current behavior.
  • Never remove a deprecated package, import, or utility just because a TODO suggests it unless the codebase proves it is unused.
  • If a fix could change logic, generated markup, CSS application, or script behavior, validate the surrounding usage first.
  • If the safe fix is unclear, ask the user instead of inventing code.
  • TODO 不是让你猜测的许可，而是提示你验证实际可安全更改的内容。
  • 修复范围内的所有可操作 TODO，但必须先根据附近代码及其用法证明每项修复是安全的。
  • 优先采用能够保留当前行为的最小改动。
  • 除非代码库能够证明某个 deprecated package、import 或 utility 未被使用，否则不要仅因 TODO 的建议就将其删除。
  • 如果某项修复可能改变逻辑、生成的标记、CSS 生效方式或脚本行为，应先验证相关用法。
  • 如果无法确定安全的修复方案，应询问用户，而不是自行编写代码。

TODO Processing Order

TODO 处理顺序

Process TODOs starting from shared modules and barrel files (
index.ts
, 
public-api.ts
) to unblock consumers, then move to services, components, and finally style entry points. Complete all TODOs in a file before moving to the next one. If a file cannot be completed, add a Quick Entry to MIGRATION_ISSUES.md and continue.
处理 TODO 时，先从共享模块和 barrel files（
index.ts
、
public-api.ts
）开始，以解除 consumers 的阻塞，然后依次处理 services、components，最后处理样式入口。完成一个文件中的所有 TODO 后，再进入下一个文件。如果某个文件无法完成，请在 
MIGRATION_ISSUES.md
中添加一个 Quick Entry，然后继续处理。

TODO Classification → Required Question Template

TODO 分类 → 必用问题模板

CategoryStop conditionQuestion to ask
Template/DI (high priority)Direct replacement existsUsually safe to fix without asking
Style package removalAny class from that package found in templates"I found 
<className>
used in 
<file>
. Should I keep the old style package until these are migrated?"
No direct replacementTODO explicitly says so"The migration notes say 
<API>
was removed with no direct replacement. What behavior should replace it?"
Dynamic binding
[input]="expr"
where expr is runtime value		"The binding 
[appearance]="mode"
uses a runtime value. Should the new API accept the same values?"
Multiple valid pathsMore than one replacement exists in docs"Two replacements exist: 
<A>
and 
<B>
. Which one matches your intended behavior?"
Warning-onlyTODO indicates manual decision needed"This TODO requires your decision: 
<TODO text>
. What is your preferred approach?"
Classification examples:
  • TODO: replace TuiButtonModule with TuiButton
    → Template/DI (high priority, usually safe)
  • TODO: remove @taiga-ui/styles import
    → Style package (STOP, check usage first)
  • TODO: migrate to standalone component API
    → TypeScript (medium priority, check consumers)
  • TODO: this API was removed, no direct replacement
    → Warning-only (ask user)
类别停止条件需要询问的问题
模板/DI（高优先级）存在直接替代项通常无需询问即可安全修复
移除样式 package在模板中发现了该 package 中的任何 class“我发现 
<file>
中使用了 
<className>
。是否应保留旧样式 package，直到这些用法完成迁移？”
没有直接替代项TODO 明确说明没有直接替代项“迁移说明指出 
<API>
已被删除且没有直接替代项。应该使用哪种行为来替代它？”
动态绑定
[input]="expr"
，其中 expr 是运行时值		“绑定 
[appearance]="mode"
使用了运行时值。新 API 是否应接受相同的值？”
存在多条有效路径文档中有多个可选替代项“存在两个替代项：
<A>
和 
<B>
。哪一个符合你的预期行为？”
仅警告TODO 表示需要手动决策“此 TODO 需要你决定：
<TODO text>
。你倾向于采用哪种方案？”
分类示例：
  • TODO: replace TuiButtonModule with TuiButton
    → 模板/DI（高优先级，通常安全）
  • TODO: remove @taiga-ui/styles import
    → 样式 package（停止，先检查用法）
  • TODO: migrate to standalone component API
    → TypeScript（中等优先级，检查 consumers）
  • TODO: this API was removed, no direct replacement
    → 仅警告（询问用户）

TODO Workflow

TODO 工作流

  1. Identify and classify the TODO using the table above
  2. Look up the replacement using MCP (if available):
    • For component replacements: call 
      get_component_example
      with the new component name
    • For architectural changes: call 
      get_overview
      or 
      migration_guide
    • Skip this step only if the replacement is unambiguous from local code context alone
  3. Trace real usage before editing anything:
    • Search the current component, template, styles, and nearby files for direct references
    • For style-related TODOs, follow the Style Package Removal algorithm below
    • Confirm whether the TODO targets one site or a broader pattern
  4. Decide whether the TODO is safely actionable:
    • If there is a one-to-one replacement and it preserves behavior, apply it
    • If a deprecated package is mentioned, check whether any runtime, template, or style usage still depends on it before deleting it
    • If multiple replacements are plausible, or the fix depends on dynamic bindings or generated output, stop and ask the user using the question template
  5. Apply the smallest safe fix:
    • Keep changes localized
    • Avoid broad refactors unless they are required to preserve behavior
    • Do not remove imports, packages, or scripts unless the surrounding evidence supports that removal
  6. Verify the result:
    • Re-read the touched area to make sure logic, classes, and selectors still line up
    • Run the narrowest available check for the affected slice when possible
    • If the change still feels ambiguous after verification, do not expand the patch; ask the user
  1. 使用上述表格识别并分类 TODO。
  2. 通过 MCP（如果可用）查找替代项：
    • 对于组件替代项：使用新组件名称调用 
      get_component_example
    • 对于架构变更：调用 
      get_overview
      或 
      migration_guide
    • 仅当本地代码上下文本身已明确说明替代项时，才可跳过此步骤
  3. 编辑前追踪实际用法：
    • 在当前组件、模板、样式和附近文件中搜索直接引用
    • 对于与样式相关的 TODO，遵循下方的样式 package 移除算法
    • 确认 TODO 针对的是单个位置，还是更广泛的模式
  4. 判断 TODO 是否可以安全处理：
    • 如果存在一对一替代项且能够保留行为，则应用该替代项
    • 如果提到某个 deprecated package，删除前应检查运行时、模板或样式是否仍依赖它
    • 如果存在多个合理替代项，或修复取决于动态绑定或生成结果，则停止并使用问题模板询问用户
  5. 应用最小安全修复：
    • 将更改限制在局部范围内
    • 除非为保留行为所必需，否则避免大规模重构
    • 除非周围证据支持删除，否则不要移除 imports、packages 或 scripts
  6. 验证结果：
    • 重新阅读修改区域，确保逻辑、classes 和 selectors 仍然匹配
    • 尽可能对受影响部分运行范围最窄的检查
    • 如果验证后仍存在歧义，不要扩大补丁范围；应询问用户

Phase 4: Troubleshooting

阶段 4：故障排查

Problem: TypeScript errors TS6133 - variable is declared but its value is never read

问题：TypeScript 错误 TS6133——变量已声明但其值从未被读取

Solution: Migration schematics don't include code formatting on purpose (it would slow down execution). Use your IDE or linter:
  • WebStorm: Right-click on root folder → "Optimize imports" (removes all unused imports recursively)
  • Visual Studio Code: Use "Organize Imports" folder source action across all files recursively
  • ESLint/Prettier: Run well-optimized rules to clean up unused imports
解决方案： 迁移 schematics 有意不包含代码格式化（因为这会拖慢执行速度）。请使用 IDE 或 linter：
  • WebStorm：右键单击根文件夹 → “Optimize imports”（递归移除所有未使用的 imports）
  • Visual Studio Code：对所有文件递归使用文件夹级 source action 中的 “Organize Imports”
  • ESLint/Prettier：运行经过良好优化的 rules 来清理未使用的 imports

Problem: Yarn users or legacy-peer-deps workaround needed

问题：Yarn 用户或需要使用 legacy-peer-deps 变通方案

Solution: Taiga UI depends on many Taiga Family packages. Yarn and pnpm do not automatically install transitive peer dependencies. Manually check each Taiga UI package's 
package.json
and install missing peer dependencies.
解决方案： Taiga UI 依赖许多 Taiga Family packages。Yarn 和 pnpm 不会自动安装传递性 peer dependencies。请手动检查每个 Taiga UI package 的 
package.json
，并安装缺失的 peer dependencies。

Problem: Cannot resolve dependency for ng-web-apis, maskito, ng-polymorpheus, or ng-event-plugins

问题：无法解析 ng-web-apis、maskito、ng-polymorpheus 或 ng-event-plugins 的依赖

Solution: Same as above - manually install transitive peer dependencies by checking each Taiga UI package's 
package.json
解决方案： 与上例相同——通过检查每个 Taiga UI package 的 
package.json
，手动安装传递性 peer dependencies。

Problem: 
Cannot find module 'ts-morph'
error after 
nx migrate --run-migrations

问题：执行 
nx migrate --run-migrations
后出现 
Cannot find module 'ts-morph'
错误

Solution: This is an Nx issue with the ng migrate command. Either:
  • Bump Nx version, or
  • Run 
    npm install
    followed by re-running the migration
解决方案： 这是 Nx 的 ng migrate 命令存在的问题。可以选择：
  • 升级 Nx 版本，或
  • 运行 
    npm install
    ，然后重新执行迁移

Problem: FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

问题：FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Solution: Migration schematics recursively traverse every file and directory, which can be memory-intensive. Increase the memory limit for the Node.js process:
bash
NODE_OPTIONS="--max-old-space-size=4096" ng update @taiga-ui/cdk
解决方案： 迁移 schematics 会递归遍历每个文件和目录，因此可能消耗大量内存。请提高 Node.js 进程的内存限制：
bash
NODE_OPTIONS="--max-old-space-size=4096" ng update @taiga-ui/cdk

Problem: Basic 
ng update
/ 
nx migrate
command fails, need to execute schematics manually

问题：基本的 
ng update
/ 
nx migrate
命令失败，需要手动执行 schematics

Solution:
  1. Manually update all Taiga UI packages to v{NEXT_MAJOR} in 
    package.json
    (change versions without console commands, then run 
    npm install
    )
  2. Verify 
    node_modules/@taiga-ui/cdk/package.json
    contains the v{NEXT_MAJOR} version
  3. Execute:
Angular CLI:
bash
ng update @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version> --to=@taiga-ui/cdk@<new-version>
Nx:
bash
nx migrate @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version>
nx migrate --run-migrations=migrations.json
解决方案：
  1. 在 
    package.json
    中手动将所有 Taiga UI packages 更新至 v{NEXT_MAJOR}（直接修改版本号而不使用控制台命令，然后运行 
    npm install
    ）
  2. 验证 
    node_modules/@taiga-ui/cdk/package.json
    中包含 v{NEXT_MAJOR} 版本
  3. 执行：
Angular CLI：
bash
ng update @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version> --to=@taiga-ui/cdk@<new-version>
Nx：
bash
nx migrate @taiga-ui/cdk --from=@taiga-ui/cdk@<old-version>
nx migrate --run-migrations=migrations.json

Documenting Uncertain or Broken Migration Points

记录不确定或损坏的迁移点

When encountering migration issues that cannot be resolved immediately, create and maintain a dedicated file (e.g., 
MIGRATION_ISSUES.md
or 
TODO_MIGRATION.md
) to track all uncertain or potentially broken areas.
遇到无法立即解决的迁移问题时，应创建并维护一个专用文件（例如 
MIGRATION_ISSUES.md
或 
TODO_MIGRATION.md
），用于跟踪所有不确定或可能损坏的区域。

Two-tier Documentation Format

两级文档格式

Quick entry (for straightforward blockers):
markdown
- [ ] `src/app/button.component.html:34` — `TuiButtonModule` TODO,
      blocked: dynamic `[appearance]` binding, need user input
Use quick entries for:
  • Single-file issues with clear blocking reason
  • Cases where the question to ask is obvious from the TODO
  • Minor style package usage that needs user decision
Full entry (only when multiple files affected or behavior change is possible):
Use the 7-field format below for:
  • Issues spanning multiple files
  • Potential behavior changes
  • Complex style package dependencies
  • Cases requiring detailed explanation
Quick entry（用于直接的阻塞问题）：
markdown
- [ ] `src/app/button.component.html:34` — `TuiButtonModule` TODO,
      blocked: dynamic `[appearance]` binding, need user input
以下情况应使用 quick entry：
  • 阻塞原因明确的单文件问题
  • 需要询问的问题由 TODO 直接决定的情况
  • 需要用户决定的小范围样式 package 使用问题
Full entry（仅当影响多个文件或可能改变行为时使用）：
以下情况应使用下方的 7 字段格式：
  • 影响多个文件的问题
  • 可能改变行为的问题
  • 复杂的样式 package 依赖关系
  • 需要详细说明的情况

Required Format for Full Entry

Full Entry 必需格式

Each documented issue must include:
  1. File path - Full relative path to the affected file (or list of files)
  2. Line number - Exact line where the issue occurs
  3. Original code - The code snippet before your attempted fix
  4. Issue description - Clear explanation of what is uncertain or broken
  5. Attempted solutions - What migration approaches you considered and why they may not work
  6. Potential impact - What could break if the wrong fix is applied (runtime, template, styles, build)
  7. Migration version - Which Taiga UI version migration this relates to (if known)
记录的每个问题都必须包含：
  1. 文件路径——受影响文件的完整相对路径（或文件列表）
  2. 行号——问题发生的准确行号
  3. 原始代码——尝试修复前的代码片段
  4. 问题描述——对不确定或损坏问题的清晰说明
  5. 已尝试的解决方案——考虑过的迁移方案，以及它们可能无效的原因
  6. 潜在影响——如果应用错误修复，可能导致哪些问题（运行时、模板、样式、构建）
  7. 迁移版本——该问题关联的 Taiga UI 迁移版本（如果已知）

Example Full Entry Format

Full Entry 格式示例

markdown
undefined
markdown
undefined

Issue #<number>: <Brief description>

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
undefined
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
undefined

Workflow Integration

工作流集成

  1. During initial scan: Create the migration issues file at the start of the migration session
  2. When blocked: Add a Quick Entry before moving to the next TODO
  3. Before asking user: Reference the documented entry in your question
  4. After resolution: Mark the entry as resolved with a brief note about the applied fix
  1. 初始扫描期间： 在迁移会话开始时创建迁移问题文件
  2. 遇到阻塞时： 在继续处理下一个 TODO 前添加一个 Quick Entry
  3. 询问用户前： 在问题中引用已记录的条目
  4. 问题解决后： 标记该条目已解决，并简要说明所应用的修复

Definition of Done

完成定义（Definition of Done）

The migration session is complete when ALL of the following are true:
  • No 
    // TODO: (Taiga UI migration)
    comments remain in source files, OR each remaining TODO has a corresponding entry in MIGRATION_ISSUES.md
  • No imports from 
    @taiga-ui/legacy
    exist, OR each remaining import is explicitly accepted by the user
  • ng build
    / 
    nx build
    completes without errors
  • No new TypeScript errors were introduced (TS6133 unused-import errors are acceptable — resolve via IDE as described in Phase 4)
  • All entries in MIGRATION_ISSUES.md have been shown to the user
Do not refactor, rename, or improve code beyond what migration requires.
当满足以下所有条件时，迁移会话即视为完成：
  • 源文件中不再存在 
    // TODO: (Taiga UI migration)
    注释，或者每个剩余 TODO 都有对应的 MIGRATION_ISSUES.md 条目
  • 不再存在来自 
    @taiga-ui/legacy
    的 imports，或者每个剩余 import 都已获得用户明确接受
  • ng build
    / 
    nx build
    执行完成且没有错误
  • 未引入新的 TypeScript 错误（TS6133 未使用 import 错误可以接受——按照阶段 4 中所述通过 IDE 解决）
  • MIGRATION_ISSUES.md 中的所有条目均已向用户展示
不要进行迁移之外的代码重构、重命名或改进。

When to Ask the User

何时询问用户

Use the question templates from the TODO Classification table for all TODO-related decisions.
Additionally, ask when:
  • Migration schematics failed or produced unexpected errors
  • The project has custom configurations that may affect migration
  • Step 0 context cannot be determined automatically
  • A peer-dependency conflict cannot be resolved by aligning Taiga UI package versions
对于所有与 TODO 相关的决策，使用 TODO 分类表中的问题模板。
此外，在以下情况下询问用户：
  • 迁移 schematics 失败或产生了意外错误
  • 项目具有可能影响迁移的自定义配置
  • 无法自动确定步骤 0 的上下文
  • 无法通过对齐 Taiga UI package 版本来解决 peer-dependency 冲突

What Not to Do

不应执行的操作

  • Do not use 
    --legacy-peer-deps
    , 
    --force
    , or any flag that bypasses dependency resolution, and do not add 
    legacy-peer-deps=true
    to 
    .npmrc
    if it was not already there     — these hide real version conflicts that will break the migration at runtime; resolve conflicts explicitly instead
  • Do not hardcode a fix based only on the TODO text
  • Do not delete deprecated dependencies first and discover breakage later
  • Do not rewrite unrelated code while chasing a migration TODO
  • Do not suppress TODOs with a new warning if the actual fix is already known and safe
  • Do not continue if you cannot explain why the change is safe from the local code context
  • Do not skip the prerequisites checklist - ensure environment is properly prepared
  • Do not skip Step 0 (Gather Context) - know your environment before acting
  • 不要使用 
    --legacy-peer-deps
    、
    --force
    ，或任何绕过依赖解析的标志；如果原本不存在，也不要将 
    legacy-peer-deps=true
    添加到 
    .npmrc
    ——这些标志会隐藏真正的版本冲突，而这些冲突会在运行时导致迁移失败；应显式解决冲突
  • 不要仅根据 TODO 文本硬编码修复方案
  • 不要先删除 deprecated dependencies，随后才发现故障
  • 不要在处理迁移 TODO 时重写无关代码
  • 如果实际修复方案已知且安全，不要用新的 warning 压制 TODO
  • 如果无法根据本地代码上下文解释为什么更改是安全的，不要继续操作
  • 不要跳过先决条件检查清单——确保环境已正确准备
  • 不要跳过步骤 0（收集上下文）——行动前必须了解环境