高级前端开发技能

高级前端开发

前端开发模式、性能优化和React/Next.js应用程序的自动化工具。

目录

• 项目脚手架
• 组件生成
• 打包分析
• React模式
• Next.js优化
• 无障碍性和测试

---

项目脚手架

使用TypeScript、Tailwind CSS和最佳实践配置生成新的Next.js或React项目。

工作流：创建新前端项目

1. 使用项目名称和模板运行脚手架工具：

   python scripts/frontend_scaffolder.py my-app --template nextjs
   

2. 添加可选功能（认证、API、表单、测试、Storybook）：

   python scripts/frontend_scaffolder.py dashboard --template nextjs --features auth,api
   

3. 进入项目目录并安装依赖：

   cd my-app && npm install
   

4. 启动开发服务器：

   npm run dev
   

脚手架选项

选项	描述
--template nextjs	使用App Router和服务器组件的Next.js 14+
--template react	React + Vite搭配TypeScript
--features auth	添加NextAuth.js认证
--features api	添加React Query + API客户端
--features forms	添加React Hook Form + Zod验证
--features testing	添加Vitest + Testing Library
--dry-run	预览文件而不实际创建

生成的结构（Next.js）

my-app/
├── app/
│   ├── layout.tsx        # 带字体的根布局
│   ├── page.tsx          # 首页
│   ├── globals.css       # Tailwind + CSS变量
│   └── api/health/route.ts
├── components/
│   ├── ui/               # 按钮、输入框、卡片
│   └── layout/           # 页眉、页脚、侧边栏
├── hooks/                # useDebounce, useLocalStorage
├── lib/                  # 工具函数 (cn), 常量
├── types/                # TypeScript接口
├── tailwind.config.ts
├── next.config.js
└── package.json

---

组件生成

使用TypeScript、测试和Storybook故事生成React组件。

工作流：创建新组件

1. 生成一个客户端组件：

   python scripts/component_generator.py Button --dir src/components/ui
   

2. 生成一个服务器组件：

   python scripts/component_generator.py ProductCard --type server
   

3. 生成带有测试和故事文件的组件：

   python scripts/component_generator.py UserProfile --with-test --with-story
   

4. 生成自定义Hook：

   python scripts/component_generator.py FormValidation --type hook
   

生成器选项

选项	描述
--type client	带有'use client'的客户端组件（默认）
--type server	异步服务器组件
--type hook	自定义React Hook
--with-test	包含测试文件
--with-story	包含Storybook故事
--flat	在输出目录中创建，不带子目录
--dry-run	预览而不创建文件

生成组件示例

'use client';

import { useState } from 'react';
import { cn } from '@/lib/utils';

interface ButtonProps {
  className?: string;
  children?: React.ReactNode;
}

export function Button({ className, children }: ButtonProps) {
  return (
    <div className={cn('', className)}>
      {children}
    </div>
  );
}

---

打包分析

分析package.json和项目结构，寻找打包优化机会。

工作流：优化打包大小

1. 在项目上运行分析器：

   python scripts/bundle_analyzer.py /path/to/project
   

2. 查看健康评分和问题：

   打包健康评分：75/100 (C)
   
   大型依赖项：
     moment (290KB)
       替代方案：date-fns (12KB) 或 dayjs (2KB)
   
     lodash (71KB)
       替代方案：lodash-es（配合摇树优化）
   

3. 通过替换大型依赖项应用推荐的修复。

4. 使用详细模式重新运行以检查导入模式：

   python scripts/bundle_analyzer.py . --verbose
   

打包评分解读

评分	等级	操作
90-100	A	打包已良好优化
80-89	B	可进行次要优化
70-79	C	替换大型依赖项
60-69	D	多个问题需要关注
0-59	F	严重的打包大小问题

检测到的大型依赖项

分析器识别这些常见的大型包：

包	大小	替代方案
moment	290KB	date-fns (12KB) 或 dayjs (2KB)
lodash	71KB	lodash-es（配合摇树优化）
axios	14KB	原生fetch或ky (3KB)
jquery	87KB	原生DOM API
@mui/material	大	shadcn/ui 或 Radix UI

---

React模式

参考：references/react_patterns.md

复合组件

在相关组件之间共享状态：

const Tabs = ({ children }) => {
  const [active, setActive] = useState(0);
  return (
    <TabsContext.Provider value={{ active, setActive }}>
      {children}
    </TabsContext.Provider>
  );
};

Tabs.List = TabList;
Tabs.Panel = TabPanel;

// 用法
<Tabs>
  <Tabs.List>
    <Tabs.Tab>一</Tabs.Tab>
    <Tabs.Tab>二</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel>内容 1</Tabs.Panel>
  <Tabs.Panel>内容 2</Tabs.Panel>
</Tabs>

自定义Hooks

提取可复用逻辑：

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

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

  return debouncedValue;
}

// 用法
const debouncedSearch = useDebounce(searchTerm, 300);

渲染属性

共享渲染逻辑：

function DataFetcher({ url, render }) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(url).then(r => r.json()).then(setData).finally(() => setLoading(false));
  }, [url]);

  return render({ data, loading });
}

// 用法
<DataFetcher
  url="/api/users"
  render={({ data, loading }) =>
    loading ? <Spinner /> : <UserList users={data} />
  }
/>

---

Next.js优化

参考：references/nextjs_optimization_guide.md

服务器组件 vs 客户端组件

默认使用服务器组件。仅当需要以下功能时添加'use client'：

• 事件处理程序（onClick, onChange）
• 状态（useState, useReducer）
• 副作用（useEffect）
• 浏览器API

// 服务器组件（默认）- 无'use client'
async function ProductPage({ params }) {
  const product = await getProduct(params.id);  // 服务器端获取

  return (
    <div>
      <h1>{product.name}</h1>
      <AddToCartButton productId={product.id} />  {/* 客户端组件 */}
    </div>
  );
}

// 客户端组件
'use client';
function AddToCartButton({ productId }) {
  const [adding, setAdding] = useState(false);
  return <button onClick={() => addToCart(productId)}>添加</button>;
}

图像优化

import Image from 'next/image';

// 首屏图像 - 立即加载
<Image
  src="/hero.jpg"
  alt="英雄图像"
  width={1200}
  height={600}
  priority
/>

// 使用fill的响应式图像
<div className="relative aspect-video">
  <Image
    src="/product.jpg"
    alt="产品图像"
    fill
    sizes="(max-width: 768px) 100vw, 50vw"
    className="object-cover"
  />
</div>

数据获取模式

// 并行获取
async function Dashboard() {
  const [user, stats] = await Promise.all([
    getUser(),
    getStats()
  ]);
  return <div>...</div>;
}

// 使用Suspense的流式渲染
async function ProductPage({ params }) {
  return (
    <div>
      <ProductDetails id={params.id} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={params.id} />
      </Suspense>
    </div>
  );
}

---

无障碍性和测试

参考：references/frontend_best_practices.md

无障碍性检查清单

1. 语义化HTML：使用正确的元素（<button>, <nav>, <main>）
2. 键盘导航：所有交互元素可聚焦
3. ARIA标签：为图标和复杂组件提供标签
4. 颜色对比度：普通文本最低4.5:1
5. 焦点指示器：可见的焦点状态

// 无障碍按钮
<button
  type="button"
  aria-label="关闭对话框"
  onClick={onClose}
  className="focus-visible:ring-2 focus-visible:ring-blue-500"
>
  <XIcon aria-hidden="true" />
</button>

// 键盘用户的跳过链接
<a href="#main-content" className="sr-only focus:not-sr-only">
  跳转到主内容
</a>

测试策略

// 使用React Testing Library的组件测试
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('按钮点击触发操作', async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>点击我</Button>);

  await userEvent.click(screen.getByRole('button'));
  expect(onClick).toHaveBeenCalledTimes(1);
});

// 测试无障碍性
test('对话框是可访问的', async () => {
  render(<Dialog open={true} title="确认" />);

  expect(screen.getByRole('dialog')).toBeInTheDocument();
  expect(screen.getByRole('dialog')).toHaveAttribute('aria-labelledby');
});

---

快速参考

常用Next.js配置

// next.config.js
const nextConfig = {
  images: {
    remotePatterns: [{ hostname: "cdnexamplecom" }],
    formats: ['image/avif', 'image/webp'],
  },
  experimental: {
    optimizePackageImports: ['lucide-react', '@heroicons/react'],
  },
};

Tailwind CSS工具函数

// 使用cn()的条件类
import { cn } from '@/lib/utils';

<button className={cn(
  'px-4 py-2 rounded',
  variant === 'primary' && 'bg-blue-500 text-white',
  disabled && 'opacity-50 cursor-not-allowed'
)} />

TypeScript模式

// 带有children的Props
interface CardProps {
  className?: string;
  children: React.ReactNode;
}

// 泛型组件
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map(renderItem)}</ul>;
}

---

资源

• React模式：references/react_patterns.md
• Next.js优化：references/nextjs_optimization_guide.md
• 最佳实践：references/frontend_best_practices.md
• 强制提问库（Matt Pocock grill）：references/forcing_questions.md
• 组合图（应分派给哪个专家）：references/composition_map.md

---

假设与可验证的成功标准（Karpathy原则）

在此技能脚手架化组件、推荐框架或审计打包之前，必须展示以下四个假设。

1. 主要用户设备 + 网络 — mobile-4G, desktop-fiber, low-end-Android, 或 corporate-network。驱动所有性能决策。
2. LCP目标（毫秒） — 一个数字，而不是“快”。驱动打包预算和渲染选择。
3. 依赖SEO vs. 需要认证 — 驱动渲染（SSR/SSG/RSC vs. SPA）。
4. WCAG目标 + 指定的无障碍负责人 — AA, AAA, 或尽力而为。驱动无障碍投资和CI关卡。

可验证的成功标准（Karpathy #4）— 每个推荐必须包括：

• 在主要设备上p75的Core Web Vitals目标（LCP, INP, CLS）
• 按路由的JS打包预算（KB-gzip）
• Lighthouse无障碍基线 + 性能基线

如果这三个中的任何一个未说明，则推荐不完整 — 返回强制提问库的Q2。

scripts/frontend_decision_engine.py工具编码了这些检查：它拒绝在没有四个假设输入的情况下推荐配置文件，并打印匹配配置文件的可验证阈值。

---

自定义配置文件

profiles/中的四个内置配置文件校准每个推荐：

配置文件	何时选择	LCP目标(mobile-4G p75)	打包预算
next-app-router	SaaS面向客户，SEO + 动态，RSC优先	2000ms	150 KB-gzip / 路由
remix-or-sveltekit	主要面向mobile-4G，低JS优先，渐进增强	1500ms	80 KB-gzip / 路由
vite-spa	需要认证的应用，主要面向桌面/企业	2500ms	200 KB初始 + 80 KB / 路由
astro-or-static	营销/文档/博客，近乎零写入，SEO关键	1200ms	30 KB JS / 页面

通过以下命令选择配置文件：

python scripts/frontend_decision_engine.py \
  --primary-device mobile-4g --lcp-target-ms 2000 \
  --seo-dependent true --auth-walled false --team-size 5

该工具返回最佳匹配配置文件、亚军权衡（如果在15%以内）、技术栈选择、该配置文件应避免的反模式以及所需的CI关卡。

要添加自定义配置文件（例如，您组织的内部工具默认值）：复制profiles/vite-spa.json到profiles/<your-org>.json并调整constraints + success_thresholds。

---

组合图

此技能不会重新实现POWERFUL级专家所负责的范围。它分派给它们。参见references/composition_map.md获取完整路由表。关键分派：

关注点	分派给
WCAG审计、对比度、屏幕阅读器	engineering-team/skills/a11y-audit/
打包分析 + 运行时性能	engineering/skills/performance-profiler/
电影/滚动叙事落地页	engineering-team/skills/epic-design/
Apple HIG（iOS / macOS / visionOS）	product-team/skills/apple-hig-expert/
预提交Karpathy审查	engineering/karpathy-coder/
预架构审查	engineering/grill-me/

cs-frontend-engineer智能体通过context: fork编排这些分派。从另一个智能体调用它，使用Agent({subagent_type: "cs-frontend-engineer", prompt: "..."})或通过/cs:frontend-rev。

…

[为翻译截断]