frontend-patterns

frontend-patterns Skill 多维度简评

类别：前端开发 / 设计模式 仓库：affaan-m/everything-claude-code 维护者：Affaan Mustafa（Anthropic 黑客松冠军，zenith.chat 作者） 上下文：Everything Claude Code (ECC) 142 个 Skill 之一

一、核心定位与价值

frontend-patterns 是 Everything Claude Code 生态中专门面向 React/Next.js 项目的模式与最佳实践速查，覆盖：

• 组件设计模式（组合、复合、Render Props）
• 自定义 Hook（状态管理、异步数据、防抖）
• 状态管理（本地、Context、服务端）
• 性能优化（懒加载、代码分割、记忆化）
• UI 最佳实践（可访问性、响应式、UX）
• TypeScript 集成

关键洞见：这是一个”知识库”型 Skill——不直接产生代码，而是确保 Claude 在生成前端代码时遵守社区主流模式。

适用场景

• 开发新的 React 组件或页面
• 设计组件架构和状态管理方案
• 优化前端性能和用户体验
• 创建可重用的自定义 Hook
• 实现复杂的 UI 交互和动画
• 重构现有前端代码

不适用场景

• Vue/Angular/Svelte → 用各自框架的 patterns
• 后端服务 → 用 backend-patterns
• 视觉设计 → 用 frontend-design / theme-factory
• 移动端原生 → 用 RN/Flutter 专属 Skill

二、核心模式库

2.1 组件模式

模式 1：组合优于继承（Composition）

// ✅ GOOD: 组合模式
interface CardProps {
  children: React.ReactNode
  variant?: 'default' | 'outlined'
}

export function Card({ children, variant = 'default' }: CardProps) {
  return <div className={`card card-${variant}`}>{children}</div>
}

export function CardHeader({ children }: { children: React.ReactNode }) {
  return <div className="card-header">{children}</div>
}

export function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>
}

// Usage
<Card>
  <CardHeader>Title</CardHeader>
  <CardBody>Content</CardBody>
</Card>

模式 2：复合组件（Compound Components）

interface TabsContextValue {
  activeTab: string
  setActiveTab: (tab: string) => void
}

const TabsContext = createContext<TabsContextValue | undefined>(undefined)

export function Tabs({ children, defaultTab }: { children: React.ReactNode; defaultTab: string }) {
  const [activeTab, setActiveTab] = useState(defaultTab)
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  )
}

export function Tab({ id, children }: { id: string; children: React.ReactNode }) {
  const context = useContext(TabsContext)
  if (!context) throw new Error('Tab must be used within Tabs')
  return (
    <button
      className={context.activeTab === id ? 'active' : ''}
      onClick={() => context.setActiveTab(id)}
    >
      {children}
    </button>
  )
}

模式 3：Render Props

interface MouseTrackerProps {
  render: (position: { x: number; y: number }) => React.ReactNode
}

export function MouseTracker({ render }: MouseTrackerProps) {
  const [position, setPosition] = useState({ x: 0, y: 0 })
  return (
    <div onMouseMove={e => setPosition({ x: e.clientX, y: e.clientY })}>
      {render(position)}
    </div>
  )
}

2.2 自定义 Hook

Hook 1：useQuery（异步数据获取）

export function useQuery<T>({
  key,
  fetcher,
  options,
}: {
  key: string
  fetcher: () => Promise<T>
  options?: UseQueryOptions<T>
}) {
  const [data, setData] = useState<T | null>(null)
  const [error, setError] = useState<Error | null>(null)
  const [loading, setLoading] = useState(false)

  const refetch = useCallback(async () => {
    setLoading(true)
    setError(null)
    try {
      const result = await fetcher()
      setData(result)
      options?.onSuccess?.(result)
    } catch (err) {
      const error = err as Error
      setError(error)
      options?.onError?.(error)
    } finally {
      setLoading(false)
    }
  }, [fetcher, options])

  useEffect(() => {
    if (options?.enabled !== false) {
      refetch()
    }
  }, [key, refetch, options?.enabled])

  return { data, error, loading, refetch }
}

Hook 2：useDebounce（防抖）

export function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {
    const handler = setTimeout(() => {
      setDebouncedValue(value)
    }, delay)
    return () => clearTimeout(handler)
  }, [value, delay])

  return debouncedValue
}

// Usage
const debouncedQuery = useDebounce(searchQuery, 500)

Hook 3：useLocalStorage

export function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    try {
      const item = window.localStorage.getItem(key)
      return item ? JSON.parse(item) : initialValue
    } catch (error) {
      return initialValue
    }
  })

  const setValue = (value: T | ((val: T) => T)) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value
      setStoredValue(valueToStore)
      window.localStorage.setItem(key, JSON.stringify(valueToStore))
    } catch (error) {
      console.error(error)
    }
  }

  return [storedValue, setValue] as const
}

2.3 状态管理分层

2.4 性能优化技术

2.5 可访问性（a11y）检查清单

// ✅ GOOD: a11y 完整
<button
  aria-label="Close dialog"
  aria-pressed={isOpen}
  onClick={onClose}
>
  <CloseIcon aria-hidden="true" />
</button>

// ✅ 键盘导航
<dialog
  ref={dialogRef}
  onKeyDown={e => e.key === 'Escape' && onClose()}
  aria-labelledby="dialog-title"
>
  <h2 id="dialog-title">{title}</h2>
</dialog>

三、完整工作流

3.1 Step 1：触发条件识别

Skill 触发词（自动应用）：

• “React component” / “React 组件”
• “Next.js page” / “Next.js 路由”
• “useState / useEffect / useQuery”
• “状态管理” / “State management”
• “组件重构” / “Component refactor”

3.2 Step 2：模式匹配

用户请求：构建一个商品列表页
Skill 输出：
- 组件模式：组合（Card + CardHeader + CardBody）
- 状态：useState（筛选）+ URL state（分页）
- 数据：useQuery（SWR）
- 性能：React.memo（卡片）+ 虚拟化（长列表）
- a11y：role="list" + aria-label

3.3 Step 3：代码生成 + 验证

// Skill 引导 Claude 生成的代码
export function ProductList() {
  const [filter, setFilter] = useState('')
  const debouncedFilter = useDebounce(filter, 500)
  const { data, loading, error } = useQuery({
    key: `products-${debouncedFilter}`,
    fetcher: () => fetchProducts(debouncedFilter),
  })

  if (loading) return <Skeleton />
  if (error) return <ErrorMessage error={error} />
  if (!data?.length) return <EmptyState />

  return (
    <ul role="list" aria-label="Products">
      {data.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </ul>
  )
}

3.4 Step 4：a11y & 性能检查

# 用 axe-core 自动跑 a11y
pnpm add -D @axe-core/react
# Storybook + axe addon
pnpm add -D @storybook/addon-a11y

四、实战场景（来自 ECC 社区案例）

场景 1：构建组件库

需求：构建可复用的设计系统。 Skill 输出：

• 复合组件模式：Tabs / Accordion / Dropdown
• 复合组件 + Context：避免 prop drilling
• 全部 TypeScript + 完整 Props 类型
• 配合 Storybook + a11y 测试

场景 2：状态管理重构

需求：从 useState 散落改成集中式。 Skill 输出：

• 评估：何时用 Context / Zustand / Redux
• 选择 Zustand：简单、TS 友好、SSR 兼容
• 拆分 store：userStore、uiStore、dataStore
• 自定义 Hook 封装：useAuth() / useCart()

场景 3：性能优化

需求：首屏加载 5 秒 → 1.5 秒。 Skill 输出：

• Lighthouse 报告分析
• 路由级代码分割
• 图片用 next/image
• 字体子集化 + preload
• 第三方脚本 next/script strategy=“lazyOnload”

五、与相关 Skills 配合

六、6 条反合理化

七、5 条实战技巧

1. TypeScript strict 模式开启："strict": true
2. ESLint + Prettier + import-sort 强制风格统一
3. Storybook + a11y addon 早期发现可访问性问题
4. React DevTools Profiler 找出 re-render 热点
5. Lighthouse CI 在 PR 阶段守门性能

八、Q&A

Q: 跟 react-best-practices (Vercel) 区别？ A: Vercel 版聚焦 Next.js 性能；frontend-patterns 更广，覆盖通用 React + Hooks + 状态管理。

Q: 跟 frontend-design 区别？ A: frontend-design 是设计美学（颜色、字体、布局）；frontend-patterns 是代码模式（组件、Hook、状态）。

Q: 适合 Vue / Angular 吗？ A: 不适合。是 React 专属。Vue 用 vue-patterns，Angular 用 ng-patterns。

Q: 触发后 Claude 会立即改代码吗？ A: 不会。它先在 SKILL.md 指导下”理解”该用什么模式，再生成代码。

Q: 能自定义模式吗？ A: 可以在 .claude/rules/typescript/react.md 中追加团队专属模式。

Q: 老项目改造适用吗？ A: 适合。Skill 引导 Claude 渐进式重构（不要一次性大改）。

九、真实踩坑案例

案例 1：useEffect 死循环

// ❌ INFINITE LOOP
function SearchInput() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])

  useEffect(() => {
    fetchResults(query).then(setResults)
  }, [query])  // OK
  // ...
}

// 但下面这样写就死循环：
const [options, setOptions] = useState({})
useEffect(() => {
  fetchData(options).then(d => setOptions(d))  // 又修改 options
}, [options])  // 死循环

Skill 会强制要求：useEffect 依赖必须是 primitive 或稳定引用，复杂对象用 useMemo。

案例 2：useState 中存对象引用导致不更新

// ❌ Bug
const [user, setUser] = useState({ name: 'Alice' })
user.name = 'Bob'  // 直接修改，React 不检测
setUser(user)  // 引用相同，不触发 re-render

Skill 会引导：用 setUser({ ...user, name: 'Bob' }) 或 immer。

案例 3：useCallback 包装简单函数过度优化

// ❌ 过度优化
const handleClick = useCallback(() => {
  console.log('clicked')
}, [])

// ✅ 简单函数不需要
const handleClick = () => {
  console.log('clicked')
}

Skill 会提示：useCallback / useMemo 仅在”子组件用 React.memo”或”作为依赖”时才有价值。

案例 4：useEffect 中忘记清理

// ❌ 内存泄漏
useEffect(() => {
  const interval = setInterval(() => console.log('tick'), 1000)
  // 忘记 clearInterval
}, [])

// ✅ 清理
useEffect(() => {
  const interval = setInterval(() => console.log('tick'), 1000)
  return () => clearInterval(interval)
}, [])

Skill 强制：每个 useEffect 都必须有 return cleanup。

案例 5：Context.Provider 滥用导致全树 re-render

// ❌ 整个 Context 改变 → 所有消费者 re-render
<AuthContext.Provider value={{ user, login, logout }}>

// ✅ 拆分 Context
<AuthStateContext.Provider value={user}>
  <AuthActionsContext.Provider value={{ login, logout }}>
    {children}
  </AuthActionsContext.Provider>
</AuthStateContext.Provider>

Skill 会引导：Context 拆分 + useMemo value。

案例 6：服务端组件误用客户端 API

// ❌ Next.js App Router
'use client'
import { headers } from 'next/headers'  // 服务端 API 误用在客户端

// ✅ 默认服务端组件，按需 'use client'

Skill 会强制：区分 Server Component vs Client Component 边界。

案例 7：列表缺 key 属性

// ❌ 用 index 作为 key
{items.map((item, i) => <Item key={i} {...item} />)}

// ✅ 用稳定 ID
{items.map(item => <Item key={item.id} {...item} />)}

Skill 自动检测：列表必须用 stable key。

十、性能基准

10.1 Lighthouse 评分（应用 Skill 后 vs 前）

10.2 包体积影响

10.3 Re-render 优化实测

// 优化前：每次父组件渲染，子组件都渲染
// 1000 个子组件
// 渲染时间：~200ms

// 优化后：用 React.memo + useCallback
// 1000 个子组件
// 渲染时间：~10ms

十一、安装

# Claude Code
/plugin marketplace add affaan-m/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

# 手动安装
git clone https://github.com/affaan-m/everything-claude-code.git
cp -r everything-claude-code/rules/common ~/.claude/rules/
cp -r everything-claude-code/rules/typescript ~/.claude/rules/

# 通用
npx skills add affaan-m/everything-claude-code --skill frontend-patterns

十二、总结

核心价值：

• React/Next.js 模式速查
• AI 生成代码时强制遵守社区标准
• 配合 ECC 整个生态（rules/agents/hooks）
• 提升一致性、性能、可访问性

适用人群：

• React/Next.js 全栈开发者
• 组件库维护者
• 前端架构师
• 用 AI 工具（Claude Code / Cursor）辅助开发的团队

投入产出比：⭐⭐⭐⭐（4/5）—— React 团队必装。

何时不要用：

• Vue/Angular/Svelte 项目
• 后端 API 服务
• 纯 HTML/CSS 项目
• 一次性 demo 脚本

参考资料

1. affaan-m/everything-claude-code GitHub
2. React 官方文档
3. Next.js 官方文档
4. WCAG 2.1 AA 标准
5. shadcn/ui 组件库

配套文档：react-best-practices 性能 | frontend-design 美学 | backend-patterns 后端