build-error-resolver

Build Error Resolver

When to Use

Use this Skill in the following situations:

• npm run build fails
• npx tsc --noEmit shows errors
• Type errors block development
• Import/module resolution errors
• Configuration file errors
• Dependency version conflicts

Core Principles

1. Minimize changes - Make only the necessary minimal changes
2. No refactoring - Do not change unrelated code
3. No architecture changes - Fix only errors, make no design changes
4. Rapid iteration - Fix one error, verify, continue to the next

Diagnostic commands

# TypeScript 類型檢查 (無輸出)
npx tsc --noEmit

# 顯示所有錯誤
npx tsc --noEmit --pretty --incremental false

# 檢查特定檔案
npx tsc --noEmit path/to/file.ts

# Next.js 建構
npm run build

# ESLint 檢查
npx eslint . --ext .ts,.tsx,.js,.jsx

Error Fixing Workflow

1. Collect all errors

npx tsc --noEmit --pretty

2. Categorize errors

• Type inference failure
• Missing type definitions
• Import/Export errors
• Configuration errors
• Dependency issues

3. Fix by priority

• Blocking build: fix first
• Type errors: fix in order
• Warnings: fix when there is time

Common Error Patterns and Fixes

1. Type inference failure

// 錯誤: Parameter 'x' implicitly has an 'any' type
function add(x, y) { return x + y }

// 修復: 加上類型註解
function add(x: number, y: number): number { return x + y }

2. Null/Undefined errors

// 錯誤: Object is possibly 'undefined'
const name = user.name.toUpperCase()

// 修復: Optional chaining
const name = user?.name?.toUpperCase()

// 或: Null check
const name = user && user.name ? user.name.toUpperCase() : ''

3. Missing properties

// 錯誤: Property 'age' does not exist on type 'User'
interface User { name: string }
const user: User = { name: 'John', age: 30 }

// 修復: 新增屬性到 interface
interface User {
  name: string
  age?: number
}

4. Import errors

// 錯誤: Cannot find module '@/lib/utils'

// 修復 1: 檢查 tsconfig paths
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

// 修復 2: 使用相對路徑
import { formatDate } from '../lib/utils'

// 修復 3: 安裝缺少的套件
npm install @/lib/utils

5. Type mismatch

// 錯誤: Type 'string' is not assignable to type 'number'
const age: number = "30"

// 修復: 轉型
const age: number = parseInt("30", 10)

6. Generic constraints

// 錯誤: Type 'T' is not assignable to type 'string'
function getLength<T>(item: T): number {
  return item.length
}

// 修復: 加上限制
function getLength<T extends { length: number }>(item: T): number {
  return item.length
}

7. React Hook errors

// 錯誤: React Hook cannot be called conditionally
function MyComponent() {
  if (condition) {
    const [state, setState] = useState(0) // 錯誤!
  }
}

// 修復: Hook 移到頂層
function MyComponent() {
  const [state, setState] = useState(0)
  if (!condition) return null
  // 使用 state
}

8. Async/Await errors

// 錯誤: 'await' only allowed within async functions
function fetchData() {
  const data = await fetch('/api/data')
}

// 修復: 加上 async
async function fetchData() {
  const data = await fetch('/api/data')
}

9. Module not found

// 錯誤: Cannot find module 'react'

// 修復: 安裝依賴
npm install react
npm install --save-dev @types/react

Minimal Change Strategy

Do:

• Add missing type annotations
• Add necessary null checks
• Fix imports/exports
• Install missing dependencies
• Update type definitions

Do not:

• Refactor unrelated code
• Change architecture
• Rename variables/functions
• Add features
• Change logic flow
• Optimize performance

Build Error Report Format

# 建構錯誤修復報告

**日期:** YYYY-MM-DD
**建構目標:** Next.js Production / TypeScript Check
**初始錯誤:** X
**已修復錯誤:** Y
**建構狀態:** 通過 / 失敗

## 已修復錯誤

### 1. [錯誤類別]
**位置:** `src/components/Card.tsx:45`
**錯誤訊息:**
Parameter 'market' implicitly has an 'any' type.

**修復:**
+function formatMarket(market: Market) {
-function formatMarket(market) {

**修改行數:** 1

## 驗證步驟

1. TypeScript 檢查通過: `npx tsc --noEmit`
2. Next.js 建構成功: `npm run build`
3. 無新錯誤產生

Error Priority

Critical (fix immediately)

• Build fails completely
• Dev server cannot start
• Production deployment is blocked

High (fix as soon as possible)

• Single file fails
• Type errors in new code
• Import errors

Medium (fix when free)

• Linter warnings
• Use of deprecated APIs
• Non-strict type issues

Quick Reference Commands

# 檢查錯誤
npx tsc --noEmit

# 清除快取重建
rm -rf .next node_modules/.cache
npm run build

# 安裝缺少的依賴
npm install

# 自動修復 ESLint
npx eslint . --fix

# 驗證 node_modules
rm -rf node_modules package-lock.json
npm install

Success Criteria

• npx tsc --noEmit returns code 0
• npm run build completes successfully
• No new errors generated
• Lines changed minimized (< 5% of affected files)
• Dev server runs normally
• Tests still pass