Frontend Engineer

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

Component Patterns

Modern React components use:

• React.FC<Props> for type safety
• React.lazy() for code splitting
• SuspenseLoader 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

Example

import React, { useState, useCallback } from 'react';
import { Box, Paper } from '@mui/material';
import { useSuspenseQuery } from '@tanstack/react-query';
import { SuspenseLoader } from '~components/SuspenseLoader';
import type { FeatureData } from '~types/feature';

interface MyComponentProps {
    id: number;
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ id, onAction }) => {
    const [state, setState] = useState<string>('');

    const { data } = useSuspenseQuery({
        queryKey: ['feature', id],
        queryFn: () => featureApi.getFeature(id),
    });

    const handleAction = useCallback(() => {
        setState('updated');
        onAction?.();
    }, [onAction]);

    return (
        <Box sx={{ p: 2 }}>
            <Paper sx={{ p: 3 }}>
                {/* Content */}
            </Paper>
        </Box>
    );
};

export default MyComponent;

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)

Example

import { useSuspenseQuery } from '@tanstack/react-query';
import { featureApi } from '../api/featureApi';

const { data } = useSuspenseQuery({
    queryKey: ['feature', id],
    queryFn: () => featureApi.getFeature(id),
});

CRITICAL RULE: No Early Returns

// ❌ NEVER - Causes layout shift
if (isLoading) {
    return <LoadingSpinner />;
}

// ✅ ALWAYS - Consistent layout
<SuspenseLoader>
    <Content />
</SuspenseLoader>

Why: Prevents Cumulative Layout Shift (CLS), better UX

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

Import Aliases

Performance Optimization

Optimization Patterns

• useMemo: Expensive computations (filter, sort, map)
• useCallback: Event handlers passed to children
• React.memo: Expensive components
• Debounced search (300-500ms)
• Memory leak prevention (cleanup in useEffect)

Code Splitting

• Split code by route or feature
• Lazy load components and assets
• Use dynamic imports

Example

const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

<Suspense fallback={<SuspenseLoader />}>
    <HeavyComponent />
</Suspense>

Routing Guide

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' }),
});

Styling Guide

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 }}>  // ✅ v7 syntax
<Grid xs={12} md={6}>             // ❌ Old syntax

Example

import type { SxProps, Theme } from '@mui/material';

const styles: Record<string, SxProps<Theme>> = {
    container: {
        p: 2,
        backgroundColor: (theme) => theme.palette.background.paper,
    },
};

TypeScript Standards

Standards

• Strict mode, no any type
• Explicit return types on functions
• Type imports: import type { User } from '~types/user'
• Component prop interfaces with JSDoc

Example

import type { User } from '~types/user';

interface MyComponentProps {
    /** User ID to display */
    userId: number;
    /** Optional callback */
    onAction?: () => void;
}

export const MyComponent: React.FC<MyComponentProps> = ({ userId, onAction }) => {
    // Implementation
};