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