Next.js 與 TypeScript 編碼規範

我的功能

• 提供專案統一的編碼標準

• 指導 AI 代理遵循最佳實踐

• 確保 TypeScript 嚴格模式和型別安全

• 統一元件設計、狀態管理和樣式撰寫方式

何時使用我

在以下情況下使用此技能：

• 撰寫新的 React 元件時

• 進行程式碼審查 (Code Review) 時

• 需要確認程式碼是否符合專案規範時

• 重構現有程式碼時

• 處理型別定義和介面設計時

• 建立新檔案或目錄結構時

核心技術棧

必須使用的套件

• Next.js: ^16.0.10 (App Router 模式)

• React: ^18.3.1

• Jotai: ^2.16.0 (狀態管理)

• Tailwind CSS: ^3.4.19 (樣式)

• TypeScript: ^5.9.3 (嚴格模式)

• i18next: ^25.7.3 (國際化)

• pnpm: 套件管理器

禁止使用的套件

❌ Redux、Zustand、Recoil (已使用 Jotai) ❌ styled-components、emotion (已使用 Tailwind CSS) ❌ Material-UI、Ant Design (使用 Tailwind CSS) ❌ axios (使用原生 fetch) ❌ next-intl、next-i18next (已使用 react-i18next)

編碼規範總覽

詳細的編碼規範和最佳實踐，請參考 AGENTS.md 檔案。

主要規範類別

1. 架構與檔案結構

• App Router 目錄結構

• 元件組織原則

• 型別定義規範

2. TypeScript 與型別安全

• 嚴格模式配置

• Interface vs Type 使用時機

• 避免 any 的具體做法

3. React 元件設計

• 函式元件優先

• Hooks 使用規則

• 效能最佳化

4. 狀態管理 (Jotai)

• Atom 定義標準

• 避免 props drilling

• 全域狀態最佳實踐

5. 樣式與 UI

• Tailwind CSS 使用規範

• 響應式設計原則

• 無障礙性要求

6. 效能最佳化

• Next.js 效能技巧

• React 效能最佳實踐

• 打包體積優化

7. 國際化 (i18n)

• i18next 配置標準

• 語言檔案管理

• 翻譯工作流程

8. 開發流程與工具

• 測試流程

• Git 工作流程整合

• 建置與部署規範

快速參考

常用模式

// 元件模式 'use client';

import { useAtomValue } from 'jotai'; import type { ComponentProps } from '@/types';

export default function Component({ prop }: ComponentProps) { const data = useAtomValue(dataAtom); return <div>{data}</div>; }

// 型別定義 interface UserData { id: string; name: string; }

// 狀態管理 export const userDataAtom = atom<UserData[]>([]);

禁止模式

// ❌ 錯誤：使用 any function processData(data: any) {}

// ❌ 錯誤：直接修改 props function Component({ data }: { data: any }) { data.modified = true; // 錯誤 }

// ❌ 錯誤：使用禁止套件 import styled from "styled-components";

驗證檢查清單

程式碼品質

• 使用 TypeScript 嚴格模式

• 避免 any 類型，使用具體型別

• 元件使用 'use client' 標記（如需要）

• 使用 interface 定義物件結構

• 正確使用 React Hooks

架構與組織

• 遵循 App Router 目錄結構

• 元件大小合理（建議 < 200 行）

• 正確使用路徑別名（@/）

• 適當的檔案組織

狀態管理

• 使用 Jotai atoms 而非 props drilling

• Atom 定義清晰且型別安全

• 避免直接修改狀態

• 使用適當的 Jotai hooks

樣式與 UI

• 使用 Tailwind CSS 類別

• 實現響應式設計

• 新增必要的 aria-label

• 避免內聯樣式（除非必要）

效能

• 使用適當的 React 最佳化（memo、useCallback）

• 避免不必要的重新渲染

• 使用動態導入（如適當）

• 優化圖片載入

相關技能

• git-workflow

• Git 工作流程規範

• i18n-workflow

• 多語言國際化流程

• readme-maintenance

• README.md 維護指南

這個技能確保您的程式碼始終符合專案標準並保持高品質！