davila7/claude-code-templates / cli-tool/components/skills/development/frontend-dev-guidelines
frontend-dev-guidelines
VerifiedFrontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, MUI v7 styling, TanStack Router, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
| resources/common-patterns.md | markdown | 8.2 KB |
| resources/complete-examples.md | markdown | 23.9 KB |
| resources/component-patterns.md | markdown | 10.6 KB |
| resources/data-fetching.md | markdown | 19.4 KB |
| resources/file-organization.md | markdown | 11.6 KB |
| resources/loading-and-error-states.md | markdown | 11.8 KB |
| resources/performance.md | markdown | 9.4 KB |
| resources/routing-guide.md | markdown | 7.0 KB |
| resources/styling-guide.md | markdown | 7.7 KB |
| resources/typescript-standards.md | markdown | 8.2 KB |
resources/complete-examples.md
View on GitHub# Complete Examples
Full working examples combining all modern patterns: React.FC, lazy loading, Suspense, useSuspenseQuery, styling, routing, and error handling.
---
## Example 1: Complete Modern Component
Combines: React.FC, useSuspenseQuery, cache-first, useCallback, styling, error handling
```typescript
/**
* User profile display component
* Demonstrates modern patterns with Suspense and TanStack Query
*/
import React, { useState, useCallback, useMemo } from 'react';
import { Box, Paper, Typography, Button, Avatar } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';
import { useSuspenseQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { userApi } from '../api/userApi';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
import type { User } from '~types/user';
// Styles object
const componentStyles: Record<string, SxProps<Theme>> = {
container: {
p: 3,
maxWidth: 600,
margin: '0 auto',
},
header: {
display: 'flex',
alignItems: 'center',
gap: 2,
mb: 3,
},
content: {
display: 'flex',
flexDirection: 'column',
gap: 2,
},
actions: {
display: 'flex',
gap: 1,
mt: 2,
},
};
interface UserProfileProps {
userId: string;
onUpdate?: () => void;
}
export const UserProfile: React.FC<UserProfileProps> = ({ userId, onUpdate }) => {
const queryClient = useQueryClient();
const { showSuccess, showError } = useMuiSnackbar();
const [isEditing, setIsEditing] = useState(false);
// Suspense query - no isLoading needed!
const { data: user } = useSuspenseQuery({
queryKey: ['user', userId],
queryFn: () => userApi.getUser(userId),
staleTime: 5 * 60 * 1000,
});
// Update mutation
const updateMutation = useMutation({
mutationFn: (updates: Partial<User>) =>
userApi.updateUser(userId, updates),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['user', userId] });
showSuccess('Profile updated');
setIsEditing(false);
onUpdate?.();
},
onError: () => {
showError('Failed to update profile');
},
});
// Memoized computed value
const fullName = useMemo(() => {
return `${user.firstName} ${user.lastName}`;
}, [user.firstName, user.lastName]);
// Event handlers with useCallback
const handleEdit = useCallback(() => {
setIsEditing(true);
}, []);
const handleSave = useCallback(() => {
updateMutation.mutate({
firstName: user.firstName,
lastName: user.lastName,
});
}, [user, updateMutation]);
const handleCancel = useCallback(() => {
setIsEditing(false);
}, []);
return (
<Paper sx={componentStyles.container}>
<Box sx={componentStyles.header}>
<Avatar sx={{ width: 64, height: 64 }}>
{user.firstName[0]}{user.lastName[0]}
</Avatar>
<Box>
<Typography variant='h5'>{fullName}</Typography>
<Typography color='text.secondary'>{user.email}</Typography>
</Box>
</Box>
<Box sx={componentStyles.content}>
<Typography>Username: {user.username}</Typography>
<Typography>Roles: {user.roles.join(', ')}</Typography>
</Box>
<Box sx={componentStyles.actions}>
{!isEditing ? (
<Button variant='contained' onClick={handleEdit}>
Edit Profile
</Button>
) : (
<>
<Button
variant='contained'
onClick={handleSave}
disabled={updateMutation.isPending}
>
{updateMutation.isPending ? 'Saving...' : 'Save'}
</Button>
<Button onClick={handleCancel}>
Cancel
</Button>
</>
)}
</Box>
</Paper>
);
};
export default UserProfile;
```
**Usage:**
```typescript
<SuspenseLoader>
<UserProfile userId='123' onUpdate={() => console.log('Updated')} />
</SuspenseLoader>
```
---
## Example 2: Complete Feature Structure
Real example based on `features/posts/`:
```
features/
users/
api/
userApi.ts # API service layer
components/
UserProfile.tsx # Main component (from Example 1)
UserList.tsx # List component
UserBlog.tsx # Blog component
modals/
DeleteUserModal.tsx # Modal component
hooks/
useSuspenseUser.ts # Suspense query hook
useUserMutations.ts # Mutation hooks
useUserPermissions.ts # Feature-specific hook
helpers/
userHelpers.ts # Utility functions
validation.ts # Validation logic
types/
index.ts # TypeScript interfaces
index.ts # Public API exports
```
### API Service (userApi.ts)
```typescript
import apiClient from '@/lib/apiClient';
import type { User, CreateUserPayload, UpdateUserPayload } from '../types';
export const userApi = {
getUser: async (userId: string): Promise<User> => {
const { data } = await apiClient.get(`/users/${userId}`);
return data;
},
getUsers: async (): Promise<User[]> => {
const { data } = await apiClient.get('/users');
return data;
},
createUser: async (payload: CreateUserPayload): Promise<User> => {
const { data } = await apiClient.post('/users', payload);
return data;
},
updateUser: async (userId: string, payload: UpdateUserPayload): Promise<User> => {
const { data } = await apiClient.put(`/users/${userId}`, payload);
return data;
},
deleteUser: async (userId: string): Promise<void> => {
await apiClient.delete(`/users/${userId}`);
},
};
```
### Suspense Hook (useSuspenseUser.ts)
```typescript
import { useSuspenseQuery } from '@tanstack/react-query';
import { userApi } from '../api/userApi';
import type { User } from '../types';
export function useSuspenseUser(userId: string) {
return useSuspenseQuery<User, Error>({
queryKey: ['user', userId],
queryFn: () => userApi.getUser(userId),
staleTime: 5 * 60 * 1000,
gcTime: 10 * 60 * 1000,
});
}
export function useSuspenseUsers() {
return useSuspenseQuery<User[], Error>({
queryKey: ['users'],
queryFn: () => userApi.getUsers(),
staleTime: 1 * 60 * 1000, // Shorter for list
});
}
```
### Types (types/index.ts)
```typescript
export interface User {
id: string;
username: string;
email: string;
firstName: string;
lastName: string;
roles: string[];
createdAt: string;
updatedAt: string;
}
export interface CreateUserPayload {
username: string;
email: string;
firstName: string;
lastName: string;
password: string;
}
export type UpdateUserPayload = Partial<Omit<User, 'id' | 'createdAt' | 'updatedAt'>>;
```
### Public Exports (index.ts)
```typescript
// Export components
export { UserProfile } from './components/UserProfile';
export { UserList } from './components/UserList';
// Export hooks
export { useSuspenseUser, useSuspenseUsers } from './hooks/useSuspenseUser';
export { useUserMutations } from './hooks/useUserMutations';
// Export API
export { userApi } from './api/userApi';
// Export types
export type { User, CreateUserPayload, UpdateUserPayload } from './types';
```
---
## Example 3: Complete Route with Lazy Loading
```typescript
/**
* User profile route
* Path: /users/:userId
*/
import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';
import { SuspenseLoader } from '~components/SuspenseLoader';
// Lazy load the UserProfile component
const UserProfile = lazy(() =>
import('@/features/users/components/UserProfile').then(
(module) => ({ default: module.UserProfile })
)
);
export const Route = createFileRoute('/users/$userId')({
component: UserProfilePage,
loader: ({ params }) => ({
crumb: `User ${params.userId}`,
}),
});
function UserProfilePage() {
const { userId } = Route.useParams();
return (
<SuspenseLoader>
<UserProfile
userId={userId}
onUpdate={() => console.log('Profile updated')}
/>
</SuspenseLoader>
);
}
export default UserProfilePage;
```
---
## Example 4: List with Search and Filtering
```typescript
import React, { useState, useMemo } from 'react';
import { Box, TextField, List, ListItem } from '@mui/material';
import { useDebounce } from 'use-debounce';
import { useSuspenseQuery } from '@tanstack/react-query';
import { userApi } from '../api/userApi';
export const UserList: React.FC = () => {
const [searchTerm, setSearchTerm] = useState('');
const [debouncedSearch] = useDebounce(searchTerm, 300);
const { data: users } = useSuspenseQuery({
queryKey: ['users'],
queryFn: () => userApi.getUsers(),
});
// Memoized filtering
const filteredUsers = useMemo(() => {
if (!debouncedSearch) return users;
return users.filter(user =>
user.name.toLowerCase().includes(debouncedSearch.toLowerCase()) ||
user.email.toLowerCase().includes(debouncedSearch.toLowerCase())
);
}, [users, debouncedSearch]);
return (
<Box>
<TextField
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
placeholder='Search users...'
fullWidth
sx={{ mb: 2 }}
/>
<List>
{filteredUsers.map(user => (
<ListItem key={user.id}>
{user.name} - {user.email}
</ListItem>
))}
</List>
</Box>
);
};
```
---
## Example 5: Blog with Validation
```typescript
import React from 'react';
import { Box, TextField, Button, Paper } from '@mui/material';
import { useBlog } from 'react-hook-blog';
import { zodResolver } from '@hookblog/resolvers/zod';
import { z } from 'zod';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { userApi } from '../api/userApi';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
const userSchema = z.object({
username: z.string().min(3).max(50),
email: z.string().email(),
firstName: z.string().min(1),
lastName: z.string().min(1),
});
type UserBlogData = z.infer<typeof userSchema>;
interface CreateUserBlogProps {
onSuccess?: () => void;
}
export const CreateUserBlog: React.FC<CreateUserBlogProps> = ({ onSuccess }) => {
const queryClient = useQueryClient();
const { showSuccess, showError } = useMuiSnackbar();
const { register, handleSubmit, blogState: { errors }, reset } = useBlog<UserBlogData>({
resolver: zodResolver(userSchema),
defaultValues: {
username: '',
email: '',
firstName: '',
lastName: '',
},
});
const createMutation = useMutation({
mutationFn: (data: UserBlogData) => userApi.createUser(data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['users'] });
showSuccess('User created successfully');
reset();
onSuccess?.();
},
onError: () => {
showError('Failed to create user');
},
});
const onSubmit = (data: UserBlogData) => {
createMutation.mutate(data);
};
return (
<Paper sx={{ p: 3, maxWidth: 500 }}>
<blog onSubmit={handleSubmit(onSubmit)}>
<Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
<TextField
{...register('username')}
label='Username'
error={!!errors.username}
helperText={errors.username?.message}
fullWidth
/>
<TextField
{...register('email')}
label='Email'
type='email'
error={!!errors.email}
helperText={errors.email?.message}
fullWidth
/>
<TextField
{...register('firstName')}
label='First Name'
error={!!errors.firstName}
helperText={errors.firstName?.message}
fullWidth
/>
<TextField
{...register('lastName')}
label='Last Name'
error={!!errors.lastName}
helperText={errors.lastName?.message}
fullWidth
/>
<Button
type='submit'
variant='contained'
disabled={createMutation.isPending}
>
{createMutation.isPending ? 'Creating...' : 'Create User'}
</Button>
</Box>
</blog>
</Paper>
);
};
export default CreateUserBlog;
```
---
## Example 2: Parent Container with Lazy Loading
```typescript
import React from 'react';
import { Box } from '@mui/material';
import { SuspenseLoader } from '~components/SuspenseLoader';
// Lazy load heavy components
const UserList = React.lazy(() => import('./UserList'));
const UserStats = React.lazy(() => import('./UserStats'));
const ActivityFeed = React.lazy(() => import('./ActivityFeed'));
export const UserDashboard: React.FC = () => {
return (
<Box sx={{ p: 2 }}>
<SuspenseLoader>
<UserStats />
</SuspenseLoader>
<Box sx={{ display: 'flex', gap: 2, mt: 2 }}>
<Box sx={{ flex: 2 }}>
<SuspenseLoader>
<UserList />
</SuspenseLoader>
</Box>
<Box sx={{ flex: 1 }}>
<SuspenseLoader>
<ActivityFeed />
</SuspenseLoader>
</Box>
</Box>
</Box>
);
};
export default UserDashboard;
```
**Benefits:**
- Each section loads independently
- User sees partial content sooner
- Better perceived perblogance
---
## Example 3: Cache-First Strategy Implementation
Complete example based on useSuspensePost.ts:
```typescript
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
import { postApi } from '../api/postApi';
import type { Post } from '../types';
/**
* Smart post hook with cache-first strategy
* Reuses data from grid cache when available
*/
export function useSuspensePost(blogId: number, postId: number) {
const queryClient = useQueryClient();
return useSuspenseQuery<Post, Error>({
queryKey: ['post', blogId, postId],
queryFn: async () => {
// Strategy 1: Check grid cache first (avoids API call)
const gridCache = queryClient.getQueryData<{ rows: Post[] }>([
'posts-v2',
blogId,
'summary'
]) || queryClient.getQueryData<{ rows: Post[] }>([
'posts-v2',
blogId,
'flat'
]);
if (gridCache?.rows) {
const cached = gridCache.rows.find(
(row) => row.S_ID === postId
);
if (cached) {
return cached; // Return from cache - no API call!
}
}
// Strategy 2: Not in cache, fetch from API
return postApi.getPost(blogId, postId);
},
staleTime: 5 * 60 * 1000, // Fresh for 5 minutes
gcTime: 10 * 60 * 1000, // Cache for 10 minutes
refetchOnWindowFocus: false, // Don't refetch on focus
});
}
```
**Why this pattern:**
- Checks grid cache before API
- Instant data if user came from grid
- Falls back to API if not cached
- Configurable cache times
---
## Example 4: Complete Route File
```typescript
/**
* Project catalog route
* Path: /project-catalog
*/
import { createFileRoute } from '@tanstack/react-router';
import { lazy } from 'react';
// Lazy load the PostTable component
const PostTable = lazy(() =>
import('@/features/posts/components/PostTable').then(
(module) => ({ default: module.PostTable })
)
);
// Route constants
const PROJECT_CATALOG_FORM_ID = 744;
const PROJECT_CATALOG_PROJECT_ID = 225;
export const Route = createFileRoute('/project-catalog/')({
component: ProjectCatalogPage,
loader: () => ({
crumb: 'Projects', // Breadcrumb title
}),
});
function ProjectCatalogPage() {
return (
<PostTable
blogId={PROJECT_CATALOG_FORM_ID}
projectId={PROJECT_CATALOG_PROJECT_ID}
tableType='active_projects'
title='Blog Dashboard'
/>
);
}
export default ProjectCatalogPage;
```
---
## Example 5: Dialog with Blog
```typescript
import React from 'react';
import {
Dialog,
DialogTitle,
DialogContent,
DialogActions,
Button,
TextField,
Box,
IconButton,
} from '@mui/material';
import { Close, PersonAdd } from '@mui/icons-material';
import { useBlog } from 'react-hook-blog';
import { zodResolver } from '@hookblog/resolvers/zod';
import { z } from 'zod';
const blogSchema = z.object({
name: z.string().min(1),
email: z.string().email(),
});
type BlogData = z.infer<typeof blogSchema>;
interface AddUserDialogProps {
open: boolean;
onClose: () => void;
onSubmit: (data: BlogData) => Promise<void>;
}
export const AddUserDialog: React.FC<AddUserDialogProps> = ({
open,
onClose,
onSubmit,
}) => {
const { register, handleSubmit, blogState: { errors }, reset } = useBlog<BlogData>({
resolver: zodResolver(blogSchema),
});
const handleClose = () => {
reset();
onClose();
};
const handleBlogSubmit = async (data: BlogData) => {
await onSubmit(data);
handleClose();
};
return (
<Dialog open={open} onClose={handleClose} maxWidth='sm' fullWidth>
<DialogTitle>
<Box sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
<Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
<PersonAdd color='primary' />
Add User
</Box>
<IconButton onClick={handleClose} size='small'>
<Close />
</IconButton>
</Box>
</DialogTitle>
<blog onSubmit={handleSubmit(handleBlogSubmit)}>
<DialogContent>
<Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
<TextField
{...register('name')}
label='Name'
error={!!errors.name}
helperText={errors.name?.message}
fullWidth
autoFocus
/>
<TextField
{...register('email')}
label='Email'
type='email'
error={!!errors.email}
helperText={errors.email?.message}
fullWidth
/>
</Box>
</DialogContent>
<DialogActions>
<Button onClick={handleClose}>Cancel</Button>
<Button type='submit' variant='contained'>
Add User
</Button>
</DialogActions>
</blog>
</Dialog>
);
};
```
---
## Example 6: Parallel Data Fetching
```typescript
import React from 'react';
import { Box, Grid, Paper } from '@mui/material';
import { useSuspenseQueries } from '@tanstack/react-query';
import { userApi } from '../api/userApi';
import { statsApi } from '../api/statsApi';
import { activityApi } from '../api/activityApi';
export const Dashboard: React.FC = () => {
// Fetch all data in parallel with Suspense
const [statsQuery, usersQuery, activityQuery] = useSuspenseQueries({
queries: [
{
queryKey: ['stats'],
queryFn: () => statsApi.getStats(),
},
{
queryKey: ['users', 'active'],
queryFn: () => userApi.getActiveUsers(),
},
{
queryKey: ['activity', 'recent'],
queryFn: () => activityApi.getRecent(),
},
],
});
return (
<Box sx={{ p: 2 }}>
<Grid container spacing={2}>
<Grid size={{ xs: 12, md: 4 }}>
<Paper sx={{ p: 2 }}>
<h3>Stats</h3>
<p>Total: {statsQuery.data.total}</p>
</Paper>
</Grid>
<Grid size={{ xs: 12, md: 4 }}>
<Paper sx={{ p: 2 }}>
<h3>Active Users</h3>
<p>Count: {usersQuery.data.length}</p>
</Paper>
</Grid>
<Grid size={{ xs: 12, md: 4 }}>
<Paper sx={{ p: 2 }}>
<h3>Recent Activity</h3>
<p>Events: {activityQuery.data.length}</p>
</Paper>
</Grid>
</Grid>
</Box>
);
};
// Usage with Suspense
<SuspenseLoader>
<Dashboard />
</SuspenseLoader>
```
---
## Example 7: Optimistic Update
```typescript
import { useMutation, useQueryClient } from '@tanstack/react-query';
import type { User } from '../types';
export const useToggleUserStatus = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (userId: string) => userApi.toggleStatus(userId),
// Optimistic update
onMutate: async (userId) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({ queryKey: ['users'] });
// Snapshot previous value
const previousUsers = queryClient.getQueryData<User[]>(['users']);
// Optimistically update UI
queryClient.setQueryData<User[]>(['users'], (old) => {
return old?.map(user =>
user.id === userId
? { ...user, active: !user.active }
: user
) || [];
});
return { previousUsers };
},
// Rollback on error
onError: (err, userId, context) => {
queryClient.setQueryData(['users'], context?.previousUsers);
},
// Refetch after mutation
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['users'] });
},
});
};
```
---
## Summary
**Key Takeaways:**
1. **Component Pattern**: React.FC + lazy + Suspense + useSuspenseQuery
2. **Feature Structure**: Organized subdirectories (api/, components/, hooks/, etc.)
3. **Routing**: Folder-based with lazy loading
4. **Data Fetching**: useSuspenseQuery with cache-first strategy
5. **Blogs**: React Hook Blog + Zod validation
6. **Error Handling**: useMuiSnackbar + onError callbacks
7. **Perblogance**: useMemo, useCallback, React.memo, debouncing
8. **Styling**: Inline <100 lines, sx prop, MUI v7 syntax
**See other resources for detailed explanations of each pattern.**Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |