135 lines
3.9 KiB
Markdown
135 lines
3.9 KiB
Markdown
---
|
||
name: ck-frontend-development
|
||
description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense-based data fetching, lazy loading, MUI v7 styling, TanStack Router, performance optimization, feature organization.
|
||
---
|
||
|
||
# ck-frontend-development
|
||
|
||
Comprehensive guide for modern React development, emphasizing Suspense-based data fetching, lazy loading, proper file organization, and performance optimization.
|
||
|
||
## When to Use
|
||
|
||
- Creating new components or pages
|
||
- Building new features with data fetching
|
||
- Setting up routing with TanStack Router
|
||
- Styling components with MUI v7
|
||
- Performance optimization of existing components
|
||
- Organizing frontend code structure
|
||
|
||
## Don't Use When
|
||
|
||
- Purely visual/design work with no data logic — use `ck-frontend-design`
|
||
- Backend API work — use `ck-backend-development`
|
||
- Testing existing components — use `ck-web-testing`
|
||
|
||
## New Component Checklist
|
||
|
||
- [ ] Use `React.FC<Props>` pattern with TypeScript
|
||
- [ ] Lazy load if heavy: `React.lazy(() => import())`
|
||
- [ ] Wrap in `<SuspenseLoader>` for loading states
|
||
- [ ] Use `useSuspenseQuery` for data fetching
|
||
- [ ] Use `useCallback` for event handlers passed to children
|
||
- [ ] Default export at bottom
|
||
- [ ] No early returns with loading spinners (causes layout shift)
|
||
|
||
## New Feature Checklist
|
||
|
||
- [ ] Create `features/{feature-name}/` directory
|
||
- [ ] Create subdirs: `api/`, `components/`, `hooks/`, `helpers/`, `types/`
|
||
- [ ] Create API service file: `api/{feature}Api.ts`
|
||
- [ ] Set up TypeScript types in `types/`
|
||
- [ ] Create route in `routes/{feature-name}/index.tsx`
|
||
- [ ] Lazy load feature components
|
||
- [ ] Export public API from feature `index.ts`
|
||
|
||
## Core Patterns
|
||
|
||
### Data Fetching — Primary Pattern: `useSuspenseQuery`
|
||
|
||
```typescript
|
||
const { data } = useSuspenseQuery({
|
||
queryKey: ['feature', id],
|
||
queryFn: () => featureApi.getFeature(id),
|
||
});
|
||
```
|
||
|
||
- Use with Suspense boundaries
|
||
- Cache-first strategy
|
||
- Replaces `isLoading` checks
|
||
|
||
### Lazy Loading
|
||
|
||
```typescript
|
||
const Heavy = React.lazy(() => import('./Heavy'));
|
||
// Always wrap in SuspenseLoader
|
||
```
|
||
|
||
### Loading States — CRITICAL RULE: No Early Returns
|
||
|
||
```typescript
|
||
// NEVER — causes layout shift
|
||
if (isLoading) return <LoadingSpinner />;
|
||
|
||
// ALWAYS — consistent layout
|
||
<SuspenseLoader><Content /></SuspenseLoader>
|
||
```
|
||
|
||
### MUI v7 Grid (breaking change)
|
||
|
||
```typescript
|
||
<Grid size={{ xs: 12, md: 6 }}> // v7 correct
|
||
<Grid xs={12} md={6}> // old — wrong
|
||
```
|
||
|
||
## File Structure
|
||
|
||
```
|
||
src/
|
||
features/
|
||
my-feature/
|
||
api/ # API service layer
|
||
components/ # Feature components
|
||
hooks/ # Custom hooks
|
||
helpers/ # Utility functions
|
||
types/ # TypeScript types
|
||
index.ts # Public exports
|
||
components/ # Truly reusable components
|
||
routes/ # TanStack Router routes
|
||
```
|
||
|
||
## Import Aliases
|
||
|
||
| Alias | Resolves To |
|
||
|-------|-------------|
|
||
| `@/` | `src/` |
|
||
| `~types` | `src/types` |
|
||
| `~components` | `src/components` |
|
||
| `~features` | `src/features` |
|
||
|
||
## Performance Patterns
|
||
|
||
- `useMemo`: Expensive computations (filter, sort, map)
|
||
- `useCallback`: Event handlers passed to children
|
||
- `React.memo`: Expensive pure components
|
||
- Debounced search: 300–500ms
|
||
- Memory leak prevention: cleanup in `useEffect`
|
||
|
||
## TypeScript Standards
|
||
|
||
- Strict mode enabled — no `any` type
|
||
- Explicit return types on functions
|
||
- Type imports: `import type { User } from '~types/user'`
|
||
- Component prop interfaces with JSDoc comments
|
||
|
||
## User Notifications
|
||
|
||
Always use `useMuiSnackbar` — never `react-toastify` or other toast libraries.
|
||
|
||
## Core Principles
|
||
|
||
1. Lazy load everything heavy: routes, DataGrid, charts, editors
|
||
2. Suspense for loading: use SuspenseLoader, not early returns
|
||
3. `useSuspenseQuery`: primary data fetching pattern
|
||
4. Features are organized: api/, components/, hooks/, helpers/
|
||
5. Styles based on size: < 100 lines inline, > 100 lines separate file
|