frontend-dev-guidelines by davila7/claude-code-templates
npx skills add https://github.com/davila7/claude-code-templates --skill frontend-dev-guidelines现代 React 开发的综合指南,强调基于 Suspense 的数据获取、懒加载、正确的文件组织和性能优化。
创建组件?请遵循此清单:
React.FC<Props> 模式React.lazy(() => import())<SuspenseLoader> 包装以处理加载状态useSuspenseQuery 进行数据获取@/、~types、、广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
~components~featuresuseCallbackuseMuiSnackbar 进行用户通知创建新功能?请设置此结构:
features/{feature-name}/ 目录api/、components/、hooks/、helpers/、types/api/{feature}Api.tstypes/ 中设置 TypeScript 类型routes/{feature-name}/index.tsx 中创建路由index.ts 导出公共 API| 别名 | 解析为 | 示例 |
|---|---|---|
@/ | src/ | import { apiClient } from '@/lib/apiClient' |
~types | src/types | import type { User } from '~types/user' |
~components | src/components | import { SuspenseLoader } from '~components/SuspenseLoader' |
~features | src/features | import { authApi } from '~features/auth' |
定义于:vite.config.ts 第 180-185 行
// React & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));
// MUI Components
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';
// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
// TanStack Router
import { createFileRoute } from '@tanstack/react-router';
// Project Components
import { SuspenseLoader } from '~components/SuspenseLoader';
// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
// Types
import type { Post } from '~types/post';
现代 React 组件使用:
React.FC<Props> 保证类型安全React.lazy() 进行代码分割SuspenseLoader 处理加载状态关键概念:
主要模式:useSuspenseQuery
isLoading 检查API 服务层:
features/{feature}/api/{feature}Api.tsapiClient axios 实例/form/route(而非 /api/form/route)features/ 与 components/ 的区别:
features/:领域特定(帖子、评论、认证)components/:真正可复用的(SuspenseLoader、CustomAppBar)功能子目录:
features/
my-feature/
api/ # API 服务层
components/ # 功能组件
hooks/ # 自定义钩子
helpers/ # 工具函数
types/ # TypeScript 类型
内联 vs 分离:
const styles: Record<string, SxProps<Theme>>100 行:单独的
.styles.ts文件
主要方法:
sx 属性SxProps<Theme> 保证类型安全(theme) => theme.palette.primary.mainMUI v7 Grid:
<Grid size={{ xs: 12, md: 6 }}> // ✅ v7 语法
<Grid xs={12} md={6}> // ❌ 旧语法
TanStack Router - 基于文件夹:
routes/my-route/index.tsxcreateFileRoute示例:
import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';
const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));
export const Route = createFileRoute('/my-route/')({
component: MyPage,
loader: () => ({ crumb: 'My Route' }),
});
关键规则:不要提前返回
// ❌ 永远不要 - 会导致布局偏移
if (isLoading) {
return <LoadingSpinner />;
}
// ✅ 始终 - 保持布局一致
<SuspenseLoader>
<Content />
</SuspenseLoader>
原因: 防止累积布局偏移(CLS),提供更好的用户体验
错误处理:
useMuiSnackbar 提供用户反馈react-toastifyonError 回调优化模式:
useMemo:昂贵的计算(过滤、排序、映射)useCallback:传递给子组件的事件处理器React.memo:昂贵的组件标准:
any 类型import type { User } from '~types/user'涵盖主题:
useAuth 钩子完整的工作示例:
| 需要... | 阅读此资源 |
|---|---|
| 创建组件 | component-patterns.md |
| 获取数据 | data-fetching.md |
| 组织文件/文件夹 | file-organization.md |
| 样式化组件 | styling-guide.md |
| 设置路由 | routing-guide.md |
| 处理加载/错误 | loading-and-error-states.md |
| 优化性能 | performance.md |
| TypeScript 类型 | typescript-standards.md |
| 表单/认证/DataGrid | common-patterns.md |
| 查看完整示例 | complete-examples.md |
src/
features/
my-feature/
api/
myFeatureApi.ts # API 服务
components/
MyFeature.tsx # 主组件
SubComponent.tsx # 相关组件
hooks/
useMyFeature.ts # 自定义钩子
useSuspenseMyFeature.ts # Suspense 钩子
helpers/
myFeatureHelpers.ts # 工具函数
types/
index.ts # TypeScript 类型
index.ts # 公共导出
components/
SuspenseLoader/
SuspenseLoader.tsx # 可复用的加载器
CustomAppBar/
CustomAppBar.tsx # 可复用的应用栏
routes/
my-route/
index.tsx # 路由组件
create/
index.tsx # 嵌套路由
import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';
interface MyComponentProps {
id: number;
onAction?: () => void;
}
export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
const [state, setState] = useState<string>('');
const { data } = useSuspenseQuery({
queryKey: ['feature', id],
queryFn: () => featureApi.getFeature(id),
});
const handleAction = useCallback(() => {
setState('updated');
onAction?.();
}, [onAction]);
return (
<Box sx={{ p: 2 }}>
<Paper sx={{ p: 3 }}>
{/* Content */}
</Paper>
</Box>
);
};
export default MyComponent;
完整示例请参阅 resources/complete-examples.md
技能状态:采用模块化结构,支持渐进式加载,以实现最佳上下文管理
每周安装数
309
仓库
GitHub 星标
22.6K
首次出现
2026年1月25日
安全审计
安装于
opencode273
gemini-cli260
codex259
github-copilot246
cursor225
claude-code223
Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
Creating a component? Follow this checklist:
React.FC<Props> pattern with TypeScriptReact.lazy(() => import())<SuspenseLoader> for loading statesuseSuspenseQuery for data fetching@/, ~types, ~components, ~featuresuseCallback for event handlers passed to childrenuseMuiSnackbar for user notificationsCreating a feature? Set up this structure:
features/{feature-name}/ directoryapi/, components/, hooks/, helpers/, types/api/{feature}Api.tstypes/routes/{feature-name}/index.tsxindex.ts| Alias | Resolves To | Example |
|---|---|---|
@/ | src/ | import { apiClient } from '@/lib/apiClient' |
~types | src/types | import type { User } from '~types/user' |
~components | src/components |
Defined in: vite.config.ts lines 180-185
// React & Lazy Loading
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));
// MUI Components
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';
// TanStack Query (Suspense)
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
// TanStack Router
import { createFileRoute } from '@tanstack/react-router';
// Project Components
import { SuspenseLoader } from '~components/SuspenseLoader';
// Hooks
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
// Types
import type { Post } from '~types/post';
Modern React components use:
React.FC<Props> for type safetyReact.lazy() for code splittingSuspenseLoader for loading statesKey Concepts:
📖 Complete Guide: resources/component-patterns.md
PRIMARY PATTERN: useSuspenseQuery
isLoading checksAPI Service Layer:
features/{feature}/api/{feature}Api.tsapiClient axios instance/form/route (NOT /api/form/route)📖 Complete Guide: resources/data-fetching.md
features/ vs components/:
features/: Domain-specific (posts, comments, auth)components/: Truly reusable (SuspenseLoader, CustomAppBar)Feature Subdirectories:
features/
my-feature/
api/ # API service layer
components/ # Feature components
hooks/ # Custom hooks
helpers/ # Utility functions
types/ # TypeScript types
📖 Complete Guide: resources/file-organization.md
Inline vs Separate:
const styles: Record<string, SxProps<Theme>>100 lines: Separate
.styles.tsfile
Primary Method:
sx prop for MUI componentsSxProps<Theme>(theme) => theme.palette.primary.mainMUI v7 Grid:
<Grid size={{ xs: 12, md: 6 }}> // ✅ v7 syntax
<Grid xs={12} md={6}> // ❌ Old syntax
📖 Complete Guide: resources/styling-guide.md
TanStack Router - Folder-Based:
routes/my-route/index.tsxcreateFileRouteExample:
import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';
const MyPage = lazy(() => import('@/features/my-feature/components/MyPage'));
export const Route = createFileRoute('/my-route/')({
component: MyPage,
loader: () => ({ crumb: 'My Route' }),
});
📖 Complete Guide: resources/routing-guide.md
CRITICAL RULE: No Early Returns
// ❌ NEVER - Causes layout shift
if (isLoading) {
return <LoadingSpinner />;
}
// ✅ ALWAYS - Consistent layout
<SuspenseLoader>
<Content />
</SuspenseLoader>
Why: Prevents Cumulative Layout Shift (CLS), better UX
Error Handling:
useMuiSnackbar for user feedbackreact-toastifyonError callbacks📖 Complete Guide: resources/loading-and-error-states.md
Optimization Patterns:
useMemo: Expensive computations (filter, sort, map)useCallback: Event handlers passed to childrenReact.memo: Expensive components📖 Complete Guide: resources/performance.md
Standards:
any typeimport type { User } from '~types/user'📖 Complete Guide: resources/typescript-standards.md
Covered Topics:
useAuth hook for current user📖 Complete Guide: resources/common-patterns.md
Full working examples:
📖 Complete Guide: resources/complete-examples.md
| Need to... | Read this resource |
|---|---|
| Create a component | component-patterns.md |
| Fetch data | data-fetching.md |
| Organize files/folders | file-organization.md |
| Style components | styling-guide.md |
| Set up routing | routing-guide.md |
| Handle loading/errors | loading-and-error-states.md |
| Optimize performance |
src/
features/
my-feature/
api/
myFeatureApi.ts # API service
components/
MyFeature.tsx # Main component
SubComponent.tsx # Related components
hooks/
useMyFeature.ts # Custom hooks
useSuspenseMyFeature.ts # Suspense hooks
helpers/
myFeatureHelpers.ts # Utilities
types/
index.ts # TypeScript types
index.ts # Public exports
components/
SuspenseLoader/
SuspenseLoader.tsx # Reusable loader
CustomAppBar/
CustomAppBar.tsx # Reusable app bar
routes/
my-route/
index.tsx # Route component
create/
index.tsx # Nested route
import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';
import type { FeatureData } from '~types/feature';
interface MyComponentProps {
id: number;
onAction?: () => void;
}
export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
const [state, setState] = useState<string>('');
const { data } = useSuspenseQuery({
queryKey: ['feature', id],
queryFn: () => featureApi.getFeature(id),
});
const handleAction = useCallback(() => {
setState('updated');
onAction?.();
}, [onAction]);
return (
<Box sx={{ p: 2 }}>
<Paper sx={{ p: 3 }}>
{/* Content */}
</Paper>
</Box>
);
};
export default MyComponent;
For complete examples, see resources/complete-examples.md
Skill Status : Modular structure with progressive loading for optimal context management
Weekly Installs
309
Repository
GitHub Stars
22.6K
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode273
gemini-cli260
codex259
github-copilot246
cursor225
claude-code223
GSAP React 动画库使用指南:useGSAP Hook 与最佳实践
1,300 周安装
LLM应用模式指南:RAG架构、AI智能体与LLMOps最佳实践
358 周安装
生物序列检索工具 - DNA/RNA/蛋白质序列跨数据库智能检索与消歧义
1,300 周安装
资深 Next.js 14+ 全栈开发专家 | App Router、服务器组件、SEO 与性能优化
1,400 周安装
Vue Pinia最佳实践:状态管理常见陷阱与解决方案指南
1,300 周安装
React项目代码修复工具 - 自动格式化与检查,提升代码质量与CI通过率
1,300 周安装
App Store Connect ID 解析器 - 快速映射应用、构建、版本等ID,提升开发效率
1,300 周安装
import { SuspenseLoader } from '~components/SuspenseLoader' |
~features | src/features | import { authApi } from '~features/auth' |
| performance.md |
| TypeScript types | typescript-standards.md |
| Forms/Auth/DataGrid | common-patterns.md |
| See full examples | complete-examples.md |