生成的结构（Next.js）

my-app/
├── app/
│   ├── layout.tsx        # 根布局，包含字体
│   ├── page.tsx          # 首页
│   ├── globals.css       # Tailwind + CSS 变量
│   └── api/health/route.ts
├── components/
│   ├── ui/               # Button、Input、Card
│   └── layout/           # Header、Footer、Sidebar
├── 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. 生成自定义钩子：

   python scripts/component_generator.py FormValidation --type hook
   

生成器选项

生成的组件示例

'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. 查看健康评分和问题：

   Bundle Health Score: 75/100 (C)
   
   HEAVY DEPENDENCIES:
     moment (290KB)
       Alternative: date-fns (12KB) or dayjs (2KB)
   
     lodash (71KB)
       Alternative: lodash-es with tree-shaking
   

3. 应用推荐的修复，替换重量级依赖项。

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

   python scripts/bundle_analyzer.py . --verbose
   

包评分解读

检测到的重量级依赖项

分析器识别这些常见的重量级包：

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>One</Tabs.Tab>
    <Tabs.Tab>Two</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel>Content 1</Tabs.Panel>
  <Tabs.Panel>Content 2</Tabs.Panel>
</Tabs>

自定义钩子

提取可重用的逻辑：

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)}>Add</button>; }

图片优化

import Image from 'next/image';

// 首屏内容 - 立即加载
<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
/>

// 响应式图片，使用 fill
<div className="relative aspect-video">
  <Image
    src="/product.jpg"
    alt="Product"
    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: 'cdn.example.com' }],
    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

每周安装次数

1

仓库

aleister1102/skills

首次出现

2026年2月3日

安全审计

Gen Agent Trust HubPass

安装于

trae1

opencode1

cursor1

kiro-cli1

codex1

github-copilot1

Scaffolder Options

Generated Structure (Next.js)

my-app/
├── app/
│   ├── layout.tsx        # Root layout with fonts
│   ├── page.tsx          # Home page
│   ├── globals.css       # Tailwind + CSS variables
│   └── api/health/route.ts
├── components/
│   ├── ui/               # Button, Input, Card
│   └── layout/           # Header, Footer, Sidebar
├── hooks/                # useDebounce, useLocalStorage
├── lib/                  # utils (cn), constants
├── types/                # TypeScript interfaces
├── tailwind.config.ts
├── next.config.js
└── package.json

Component Generation

Generate React components with TypeScript, tests, and Storybook stories.

Workflow: Create a New Component

1. Generate a client component:

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

2. Generate a server component:

   python scripts/component_generator.py ProductCard --type server
   

3. Generate with test and story files:

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

4. Generate a custom hook:

   python scripts/component_generator.py FormValidation --type hook
   

Generator Options

Generated Component Example

'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>
  );
}

Bundle Analysis

Analyze package.json and project structure for bundle optimization opportunities.

Workflow: Optimize Bundle Size

1. Run the analyzer on your project:

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

2. Review the health score and issues:

   Bundle Health Score: 75/100 (C)
   
   HEAVY DEPENDENCIES:
     moment (290KB)
       Alternative: date-fns (12KB) or dayjs (2KB)
   
     lodash (71KB)
       Alternative: lodash-es with tree-shaking
   

3. Apply the recommended fixes by replacing heavy dependencies.

4. Re-run with verbose mode to check import patterns:

   python scripts/bundle_analyzer.py . --verbose
   

Bundle Score Interpretation

Heavy Dependencies Detected

The analyzer identifies these common heavy packages:

React Patterns

Reference: references/react_patterns.md

Compound Components

Share state between related components:

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

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

// Usage
<Tabs>
  <Tabs.List>
    <Tabs.Tab>One</Tabs.Tab>
    <Tabs.Tab>Two</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel>Content 1</Tabs.Panel>
  <Tabs.Panel>Content 2</Tabs.Panel>
</Tabs>

Custom Hooks

Extract reusable logic:

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;
}

// Usage
const debouncedSearch = useDebounce(searchTerm, 300);

Render Props

Share rendering logic:

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 });
}

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

Next.js Optimization

Reference: references/nextjs_optimization_guide.md

Server vs Client Components

Use Server Components by default. Add 'use client' only when you need:

• Event handlers (onClick, onChange)

• State (useState, useReducer)

• Effects (useEffect)

• Browser APIs

  // Server Component (default) - no 'use client' async function ProductPage({ params }) { const product = await getProduct(params.id); // Server-side fetch

  return ( <div> <h1>{product.name}</h1> <AddToCartButton productId={product.id} /> {/* Client component */} </div> ); }

  // Client Component 'use client'; function AddToCartButton({ productId }) { const [adding, setAdding] = useState(false); return <button onClick={() => addToCart(productId)}>Add</button>; }

Image Optimization

import Image from 'next/image';

// Above the fold - load immediately
<Image
  src="/hero.jpg"
  alt="Hero"
  width={1200}
  height={600}
  priority
/>

// Responsive image with fill
<div className="relative aspect-video">
  <Image
    src="/product.jpg"
    alt="Product"
    fill
    sizes="(max-width: 768px) 100vw, 50vw"
    className="object-cover"
  />
</div>

Data Fetching Patterns

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

// Streaming with Suspense
async function ProductPage({ params }) {
  return (
    <div>
      <ProductDetails id={params.id} />
      <Suspense fallback={<ReviewsSkeleton />}>
        <Reviews productId={params.id} />
      </Suspense>
    </div>
  );
}

Accessibility and Testing

Reference: references/frontend_best_practices.md

Accessibility Checklist

1. Semantic HTML : Use proper elements (<button>, <nav>, <main>)
2. Keyboard Navigation : All interactive elements focusable
3. ARIA Labels : Provide labels for icons and complex widgets
4. Color Contrast : Minimum 4.5:1 for normal text
5. Focus Indicators : Visible focus states

// Accessible button

<button
  type="button"
  aria-label="Close dialog"
  onClick={onClose}
  className="focus-visible:ring-2 focus-visible:ring-blue-500"
>
  <XIcon aria-hidden="true" />
</button>

// Skip link for keyboard users
<a href="#main-content" className="sr-only focus:not-sr-only">
  Skip to main content
</a>

Testing Strategy

// Component test with React Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('button triggers action on click', async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>Click me</Button>);

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

// Test accessibility
test('dialog is accessible', async () => {
  render(<Dialog open={true} title="Confirm" />);

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

Quick Reference

Common Next.js Config

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

Tailwind CSS Utilities

// Conditional classes with 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 Patterns

// Props with children
interface CardProps {
  className?: string;
  children: React.ReactNode;
}

// Generic component
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

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

Resources

• React Patterns: references/react_patterns.md
• Next.js Optimization: references/nextjs_optimization_guide.md
• Best Practices: references/frontend_best_practices.md

Weekly Installs

1

Repository

aleister1102/skills

First Seen

Feb 3, 2026

Security Audits

Gen Agent Trust HubPass

Installed on

trae1

opencode1

cursor1

kiro-cli1

codex1

github-copilot1