Frontend Development Guidelines
Purpose
Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
When to Use This Skill
- Creating new components or pages
- Building new features
- Fetching data with TanStack Query
- Setting up routing with TanStack Router
- Styling components with MUI v7
- Performance optimization
- Organizing frontend code
- TypeScript best practices
Quick Start
New Component Checklist
Creating a component? Follow this checklist:
New Feature Checklist
Creating a feature? Set up this structure:
Import Aliases Quick Reference
| Alias |
Resolves To |
Example |
@/ |
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' |
Defined in: vite.config.ts lines 180-185
Common Imports Cheatsheet
import React, { useState, useCallback, useMemo } from 'react';
const Heavy = React.lazy(() => import('./Heavy'));
import { Box, Paper, Typography, Button, Grid } from '@mui/material';
import type { SxProps, Theme } from '@mui/material';
import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
import { createFileRoute } from '@tanstack/react-router';
import { SuspenseLoader } from '~components/SuspenseLoader';
import { useAuth } from '@/hooks/useAuth';
import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
import type { Post } from '~types/post';
Topic Guides
🎨 Component Patterns
Modern React components use:
React.FC<Props> for type safetyReact.lazy() for code splittingSuspenseLoader for loading states- Named const + default export pattern
Key Concepts:
- Lazy load heavy components (DataGrid, charts, editors)
- Always wrap lazy components in Suspense
- Use SuspenseLoader component (with fade animation)
- Component structure: Props → Hooks → Handlers → Render → Export
📖 Complete Guide: resources/component-patterns.md
📊 Data Fetching
PRIMARY PATTERN: useSuspenseQuery
- Use with Suspense boundaries
- Cache-first strategy (check grid cache before API)
- Replaces
isLoading checks
- Type-safe with generics
API Service Layer:
- Create
features/{feature}/api/{feature}Api.ts
- Use
apiClient axios instance
- Centralized methods per feature
- Route format:
/form/route (NOT /api/form/route)
📖 Complete Guide: resources/data-fetching.md
📁 File Organization
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
🎨 Styling
Inline vs Separate:
- <100 lines: Inline
const styles: Record<string, SxProps<Theme>>
-
100 lines: Separate .styles.ts file
Primary Method:
- Use
sx prop for MUI components
- Type-safe with
SxProps<Theme>
- Theme access:
(theme) => theme.palette.primary.main
MUI v7 Grid:
<Grid size={{ xs: 12, md: 6 }}>
<Grid xs={12} md={6}>
📖 Complete Guide: resources/styling-guide.md
🛣️ Routing
TanStack Router - Folder-Based:
- Directory:
routes/my-route/index.tsx
- Lazy load components
- Use
createFileRoute
- Breadcrumb data in loader
Example:
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
⏳ Loading & Error States
CRITICAL RULE: No Early Returns
if (isLoading) {
return <LoadingSpinner />;
}
<SuspenseLoader>
<Content />
</SuspenseLoader>
Why: Prevents Cumulative Layout Shift (CLS), better UX
Error Handling:
- Use
useMuiSnackbar for user feedback
- NEVER
react-toastify
- TanStack Query
onError callbacks
📖 Complete Guide: resources/loading-and-error-states.md
⚡ Performance
Optimization Patterns:
useMemo: Expensive computations (filter, sort, map)useCallback: Event handlers passed to childrenReact.memo: Expensive components- Debounced search (300-500ms)
- Memory leak prevention (cleanup in useEffect)
📖 Complete Guide: resources/performance.md
📘 TypeScript
Standards:
- Strict mode, no
any type
- Explicit return types on functions
- Type imports:
import type { User } from '~types/user'
- Component prop interfaces with JSDoc
📖 Complete Guide: resources/typescript-standards.md
🔧 Common Patterns
Covered Topics:
- React Hook Form with Zod validation
- DataGrid wrapper contracts
- Dialog component standards
useAuth hook for current user- Mutation patterns with cache invalidation
📖 Complete Guide: resources/common-patterns.md
📚 Complete Examples
Full working examples:
- Modern component with all patterns
- Complete feature structure
- API service layer
- Route with lazy loading
- Suspense + useSuspenseQuery
- Form with validation
📖 Complete Guide: resources/complete-examples.md
Navigation Guide
Core Principles
- Lazy Load Everything Heavy: Routes, DataGrid, charts, editors
- Suspense for Loading: Use SuspenseLoader, not early returns
- useSuspenseQuery: Primary data fetching pattern for new code
- Features are Organized: api/, components/, hooks/, helpers/ subdirs
- Styles Based on Size: <100 inline, >100 separate
- Import Aliases: Use @/, ~types, ~components, ~features
- No Early Retur
