code-review-react-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

使用情境與工作流程

Usage Scenarios and Workflow

第一階段（發現問題）：用本 skill 的檢查清單掃描給定的 React/TypeScript 程式碼，列出「可能有的問題」與所屬類別。
第二階段（解法與 comment）：針對每個發現的問題，讀取
references/
資料夾內對應檔案，取得該問題的建議解法與 review comment 範本，再產出具體的優化建議或評論。

本 skill 主體只保留「要檢查什麼」；具體的程式範例、解法與 review comment 皆在 references/
下，需要時再讀取以節省 token。

Phase 1 (Identify Issues)：Use this skill's checklist to scan the given React/TypeScript code, list potential issues and their categories.
Phase 2 (Solutions & Comments)：For each identified issue, read the corresponding file in the
references/
folder to get recommended solutions and review comment templates, then generate specific optimization suggestions or comments.

The main body of this skill only retains what to check; specific code examples, solutions, and review comments are all under references/
, and should be read when needed to save tokens.

審查優先順序（從上到下）

Review Priority (Top to Bottom)

優先級	內容
High（必修）	Security、Type safety、Logic bugs、Performance
Medium（應修）	Architecture、Accessibility、Tests、Error handling
Low（建議）	Coding style / API 設計偏好（見第 9 類）、命名、小優化
忽略	純個人風格、團隊未共識的偏好、bikeshedding

先處理高優先級，再往下。若先評論縮排再談型別安全，順序就錯了。

Priority	Content
High (Mandatory)	Security, Type safety, Logic bugs, Performance
Medium (Recommended)	Architecture, Accessibility, Tests, Error handling
Low (Suggested)	Coding style / API design preferences (see Category 9), Naming, Minor optimizations
Ignore	Pure personal style, preferences not agreed upon by the team, bikeshedding

Handle high-priority items first, then move downwards. It would be incorrect to comment on indentation before addressing type safety.

檢查清單（發現問題用）

Checklist (For Identifying Issues)

掃描時對照下列 red flags。若發現某項，請讀取對應的 reference 檔案取得解法與 review comment。

Scan against the following red flags. If an item is found, read the corresponding reference file to get solutions and review comments.

1. Type Safety（高） →

references/01-type-safety.md

1. Type Safety (High) →

references/01-type-safety.md

Type assertions（
```
as
```
）無合理理由
缺少 null/undefined 檢查
型別縮窄不正確（例如只靠
```
if (value)
```
無法縮窄 union）

Type assertions (
```
as
```
) without valid reasons
Missing null/undefined checks
Incorrect type narrowing (e.g., relying solely on
```
if (value)
```
cannot narrow a union type)

2. React Patterns（高） →

references/02-react-patterns.md

2. React Patterns (High) →

references/02-react-patterns.md

3. Performance（高） →

references/03-performance.md

3. Performance (High) →

references/03-performance.md

在 render 中做昂貴計算（未 useMemo）
整包匯入大型套件（如
```
import _ from 'lodash'
```
）
列表用 index 當 key 或沒有 key
高頻互動（mousemove、拖拉、動畫）用 setState 觸發 re-render，且該值不需被其他元件讀取（應改用 useRef 直接寫 DOM）

Expensive calculations in render (not using useMemo)
Importing entire large libraries (e.g.,
```
import _ from 'lodash'
```
)
Using index as key or no key for lists
Using setState to trigger re-renders for high-frequency interactions (mousemove, drag-and-drop, animations) where the value doesn't need to be read by other components (should use useRef to write directly to DOM instead)

4. Security（高） →

references/04-security.md

4. Security (High) →

references/04-security.md

潛在 XSS（未 sanitize 的
```
dangerouslySetInnerHTML
```
）
敏感資料外洩（硬編碼 key、log 密碼等）
未經編碼的使用者輸入用於 API（如 query 字串）

Potential XSS (unsanitized
```
dangerouslySetInnerHTML
```
)
Sensitive data leakage (hardcoded keys, logging passwords, etc.)
Unencoded user input used in APIs (e.g., query strings)

5. Architecture（中） →

references/05-architecture.md

5. Architecture (Medium) →

references/05-architecture.md

God component（單一元件過大、職責過多）
Prop drilling 過深
業務邏輯與 UI 混在元件內

God component (single component is too large and has excessive responsibilities)
Excessive prop drilling
Business logic mixed with UI in components

6. Accessibility（中） →

references/06-accessibility.md

6. Accessibility (Medium) →

references/06-accessibility.md

缺少語意化 HTML（例如用 div 當按鈕）
僅圖示按鈕缺少 ARIA 或可見文字
可互動元素無法用鍵盤操作

Lack of semantic HTML (e.g., using div as a button)
Icon-only buttons missing ARIA attributes or visible text
Interactive elements cannot be operated via keyboard

7. Error Handling（中） →

references/07-error-handling.md

7. Error Handling (Medium) →

references/07-error-handling.md

Promise 未處理 rejection（無 .catch / try-catch）
catch 後靜默吞錯、未回饋使用者

Unhandled Promise rejections (no .catch / try-catch)
Silently swallowing errors after catch, no feedback to users

8. Testing（中） →

references/08-testing.md

8. Testing (Medium) →

references/08-testing.md

邏輯/API 寫在元件內難以測試
關鍵流程（如支付）缺少對應測試

Logic/APIs written inside components making them hard to test
Key flows (e.g., payment) lack corresponding tests

9. Coding Style / API Design（低，建議性） →

references/09-coding-style.md

9. Coding Style / API Design (Low, Suggestive) →

references/09-coding-style.md

非 red flag，採用與否不影響正確性。以 🟡 SUGGESTION 提出，作者可不採納。

由上而下：修改成本由低到高（重命名 → 改型別 → API 重塑）。

🟢 簡單（重命名 / 改型別即可）

Boolean prop 缺少
```
is
```
/
```
has
```
/
```
should
```
前綴（除非鏡射原生 HTML 屬性）
Callback prop 沒用
```
on*
```
命名（如
```
change
```
而非
```
onChange
```
、
```
onValueChange
```
）

Prop 名稱重複 component context（

<Dialog isDialogOpen />

、

<Button buttonColor />

）

Prop 型別過寬（用
```
string
```
但實際只接受少數值，應改 union literal / template literal）
包裝原生 HTML 元素的元件沒繼承
```
React.ComponentProps<'tag'>
```
，導致
```
onClick
```
/
```
aria-*
```
/
```
className
```
無法傳入

🟡 中等（小幅 API / 型別調整）

用多個互斥 boolean 表達狀態，產生不可能的組合（建議改 enum / variant）
新增 boolean prop 表達其實可由既有 prop 推導的行為（如
```
isClosable
```
與
```
onClose
```
並存）
Render prop 用泛用
```
children
```
function，不知道參數意義（建議命名
```
renderItem(item, state)
```
）
Variant-dependent props 用普通 optional union，型別允許不可能組合（建議改 discriminated union）
```
value
```
/
```
onChange
```
/
```
options
```
等共生型別寫死，未用 generic 連動推論

🔴 較大（API 結構重塑）

自訂表單元件只支援 controlled 或只支援 uncontrolled（應鏡射原生
```
value
```
/
```
defaultValue
```
）
元件已累積 4+ 個 boolean / className prop 控制內部部位（建議考慮 compound component）
把 UI 結構塞進 data array 設定（如
```
items={[{label, icon, submenu...}]}
```
），失去 JSX 表達力

Not a red flag; adoption does not affect correctness. Present as 🟡 SUGGESTION, authors may choose not to adopt.

From top to bottom: modification cost increases from low to high (renaming → type changes → API restructuring).

🟢 Simple (renaming / type changes only)

Boolean props lack
```
is
```
/
```
has
```
/
```
should
```
prefixes (unless mirroring native HTML attributes)
Callback props not named with
```
on*
```
(e.g.,
```
change
```
instead of
```
onChange
```
,
```
onValueChange
```
)

Prop names duplicate component context (

<Dialog isDialogOpen />

<Button buttonColor />

)

Prop types are too broad (using
```
string
```
when only a few values are actually accepted; should change to union literal / template literal)
Components wrapping native HTML elements do not inherit
```
React.ComponentProps<'tag'>
```
, causing
```
onClick
```
/
```
aria-*
```
/
```
className
```
to be unpassable

🟡 Medium (minor API / type adjustments)

Using multiple mutually exclusive booleans to represent state, creating impossible combinations (suggest changing to enum / variant)
Adding boolean props for behaviors that can actually be derived from existing props (e.g.,
```
isClosable
```
coexisting with
```
onClose
```
)
Render props using generic
```
children
```
functions with unclear parameter meanings (suggest naming
```
renderItem(item, state)
```
)
Variant-dependent props using ordinary optional unions, allowing impossible type combinations (suggest changing to discriminated union)
Symbiotic types like
```
value
```
/
```
onChange
```
/
```
options
```
are hardcoded, not linked via generics for inference

🔴 Major (API structure restructuring)

Custom form components only support controlled or uncontrolled mode (should mirror native
```
value
```
/
```
defaultValue
```
)
Components have accumulated 4+ boolean / className props to control internal parts (suggest considering compound components)
UI structure is embedded in data arrays for configuration (e.g.,
```
items={[{label, icon, submenu...}]}
```
), losing JSX expressiveness

Review 原則（撰寫 comment 時參考）

Review Principles (Reference When Writing Comments)

用問句取代命令： 「Could we use useMemo here?」而非「Use useMemo.」
說明原因： 不只說「加 error handling」，要說「若 API 失敗使用者不知道，建議用 toast 改善 UX」。
提供選項： 例如「(1) 抽成 custom hook (2) 用 React Query 做 cache」。
標示嚴重度：
- 🔴 BLOCKING：例如 XSS、嚴重型別/邏輯錯誤
- 🟡 SUGGESTION：可優化（如 useMemo）
- 🟢 PRAISE：值得肯定的寫法
專注： Type safety、React 規則、效能、安全、架構。
忽略： 個人風格、主觀偏好、bikeshedding。

Use questions instead of commands: "Could we use useMemo here?" instead of "Use useMemo."
Explain the reason: Don't just say "Add error handling"; instead, say "If the API fails, users won't be aware. Suggest using a toast to improve UX."
Provide options: For example, "(1) Extract into a custom hook (2) Use React Query for caching".
Mark severity:
- 🔴 BLOCKING: e.g., XSS, critical type/logic errors
- 🟡 SUGGESTION: Optimizable (e.g., useMemo)
- 🟢 PRAISE: Worthwhile writing style
Stay focused: Type safety, React rules, performance, security, architecture.
Ignore: Personal style, subjective preferences, bikeshedding.

總結

Summary

掃描階段：用上面清單找出問題與類別，不在此處展開程式碼與長篇解法。
產出階段：對每個問題開啟對應的
```
references/XX-...md
```
，依其內容產出解法與 review comment。

Scanning Phase: Use the above checklist to identify issues and categories; do not expand on code or long-form solutions here.
Output Phase: For each issue, open the corresponding
```
references/XX-...md
```
file and generate solutions and review comments based on its content.

code-review-react-ts

Original

Translation

使用情境與工作流程

Usage Scenarios and Workflow

審查優先順序（從上到下）

Review Priority (Top to Bottom)

檢查清單（發現問題用）

Checklist (For Identifying Issues)

1. Type Safety（高） →
`references/01-type-safety.md`

1. Type Safety (High) →
`references/01-type-safety.md`

2. React Patterns（高） →
`references/02-react-patterns.md`

2. React Patterns (High) →
`references/02-react-patterns.md`

3. Performance（高） →
`references/03-performance.md`

3. Performance (High) →
`references/03-performance.md`

4. Security（高） →
`references/04-security.md`

4. Security (High) →
`references/04-security.md`

5. Architecture（中） →
`references/05-architecture.md`

5. Architecture (Medium) →
`references/05-architecture.md`

6. Accessibility（中） →
`references/06-accessibility.md`

6. Accessibility (Medium) →
`references/06-accessibility.md`

7. Error Handling（中） →
`references/07-error-handling.md`

7. Error Handling (Medium) →
`references/07-error-handling.md`

8. Testing（中） →
`references/08-testing.md`

8. Testing (Medium) →
`references/08-testing.md`

9. Coding Style / API Design（低，建議性） →
`references/09-coding-style.md`

9. Coding Style / API Design (Low, Suggestive) →
`references/09-coding-style.md`

Review 原則（撰寫 comment 時參考）

Review Principles (Reference When Writing Comments)

總結

Summary