---
name: frontend-engineer
description: Frontend 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.
license: MIT
---

# Frontend Engineer

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
- Fetching data with TanStack Query
- Setting up routing with TanStack Router
- Styling components
- Performance optimization
- Organizing frontend code
- TypeScript best practices

## Quick Start

### New Component Checklist

- [ ] Use `React.FC<Props>` pattern with TypeScript
- [ ] Lazy load if heavy component: `React.lazy(() => import())`
- [ ] Wrap in `<SuspenseLoader>` for loading states
- [ ] Use `useSuspenseQuery` for data fetching
- [ ] Import aliases: `@/`, `~types`, `~components`, `~features`
- [ ] Styles: Inline if <100 lines, separate file if >100 lines
- [ ] Use `useCallback` for event handlers passed to children
- [ ] Default export at bottom
- [ ] No early returns with loading spinners
- [ ] Use notification system for user feedback

### New Feature Checklist

- [ ] Create `features/{feature-name}/` directory
- [ ] Create subdirectories: `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
- [ ] Use Suspense boundaries
- [ ] Export public API from feature `index.ts`

## 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 for new code
4. **Features are Organized:** api/, components/, hooks/, helpers/ subdirs
5. **Styles Based on Size:** <100 inline, >100 separate
6. **Import Aliases:** Use @/, ~types, ~components, ~features
7. **No Early Returns:** Prevents layout shift
8. **TypeScript First:** Strict mode, no `any` type

## Implementation Workflow

When implementing frontend code:
- Check for existing workflow patterns (spec-first, TDD, etc.) and follow them
- Ensure code passes CI checks (types, tests, lint) before committing
- Group related changes with tests in atomic commits

## References

For detailed guidance, see:
- `references/component-patterns.md` - Modern React component patterns
- `references/data-fetching.md` - Suspense-based data fetching
- `references/file-organization.md` - Feature-based organization
- `references/styling-guide.md` - Styling patterns and best practices
- `references/routing-guide.md` - TanStack Router patterns
- `references/performance.md` - Performance optimization
- `references/typescript-standards.md` - TypeScript best practices