Frontend Dev Guidelines

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:

• 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 useMuiSnackbar for user notifications

New Feature Checklist

Creating a feature? Set up this structure:

• 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

Import Aliases Quick Reference

Defined in: vite.config.ts lines 180-185

Common Imports Cheatsheet

// React & Lazy Loadingimport React, { useState, useCallback, useMemo } from 'react';const Heavy = React.lazy(() => import('./Heavy'));
// MUI Componentsimport { Box, Paper, Typography, Button, Grid } from '@mui/material';import type { SxProps, Theme } from '@mui/material';
// TanStack Query (Suspense)import { useSuspenseQuery, useQueryClient } from '@tanstack/react-query';
// TanStack Routerimport { createFileRoute } from '@tanstack/react-router';
// Project Componentsimport { SuspenseLoader } from '~components/SuspenseLoader';
// Hooksimport { useAuth } from '@/hooks/useAuth';import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
// Typesimport type { Post } from '~types/post';

Topic Guides

🎨 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

📖 Complete Guide: resources/component-patterns.md [blocked]

📊 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 [blocked]

📁 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 [blocked]

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

📖 Complete Guide: resources/styling-guide.md [blocked]

🛣️ 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 [blocked]

⏳ Loading & Error States

CRITICAL RULE: No Early Returns

// ❌ NEVER - Causes layout shiftif (isLoading) {    return <LoadingSpinner />;}
// ✅ ALWAYS - Consistent layout<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 [blocked]

⚡ Performance

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)

📖 Complete Guide: resources/performance.md [blocked]

📘 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 [blocked]

🔧 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 [blocked]

📚 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 [blocked]

Navigation Guide

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. useMuiSnackbar: For all user notifications

Quick Reference: File Structure

src/  features/    my-feature/      api/        myFeatureApi.ts       # API service      components/        MyFeature.tsx         # Main component        SubComponent.tsx      # Related components      hooks/        useMyFeature.ts       # Custom hooks        useSuspenseMyFeature.ts  # Suspense hooks      helpers/        myFeatureHelpers.ts   # Utilities      types/        index.ts              # TypeScript types      index.ts                # Public exports
  components/    SuspenseLoader/      SuspenseLoader.tsx      # Reusable loader    CustomAppBar/      CustomAppBar.tsx        # Reusable app bar
  routes/    my-route/      index.tsx               # Route component      create/        index.tsx             # Nested route

Modern Component Template (Quick Copy)

import React, { useState, useCallback } from 'react';import { Box, Paper } from '@mui/material';import { useSuspenseQuery } from '@tanstack/react-query';import { featureApi } from '../api/featureApi';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;

For complete examples, see resources/complete-examples.md [blocked]

Related Skills

• error-tracking: Error tracking with Sentry (applies to frontend too)
• backend-dev-guidelines: Backend API patterns that frontend consumes

Skill Status: Modular structure with progressive loading for optimal context management