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

Alias Resolves To Example

src/

import { apiClient } from '@/lib/apiClient'

~types

src/types

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

~components

src/components

import { SuspenseLoader } from '~components/SuspenseLoader'

~features

src/features

import { authApi } from '~features/auth'

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

Common Imports Cheatsheet

// React & Lazy Loading import React, { useState, useCallback, useMemo } from 'react'; const Heavy = React.lazy(() => import('./Heavy'));

// MUI Components import { 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 Router import { createFileRoute } from '@tanstack/react-router';

// Project Components import { SuspenseLoader } from '~components/SuspenseLoader';

// Hooks import { useAuth } from '@/hooks/useAuth'; import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';

// Types import 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

📊 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

📁 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

🎨 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

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

⏳ Loading & Error States

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

Error Handling:

Use useMuiSnackbar for user feedback
NEVER react-toastify
TanStack Query onError callbacks

📖 Complete Guide: resources/loading-and-error-states.md

⚡ 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

📘 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

🔧 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

📚 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

Navigation Guide

Need to... Read this resource

Create a component component-patterns.md

Fetch data data-fetching.md

Organize files/folders file-organization.md

Style components styling-guide.md

Set up routing routing-guide.md

Handle loading/errors loading-and-error-states.md

Optimize performance performance.md

TypeScript types typescript-standards.md

Forms/Auth/DataGrid common-patterns.md

See full examples complete-examples.md

Core Principles

Lazy Load Everything Heavy: Routes, DataGrid, charts, editors
Suspense for Loading: Use SuspenseLoader, not early returns
useSuspenseQuery: Primary data fetching pattern for new code
Features are Organized: api/, components/, hooks/, helpers/ subdirs
Styles Based on Size: <100 inline, >100 separate
Import Aliases: Use @/, ~types, ~components, ~features
No Early Returns: Prevents layout shift
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 (
    &#x3C;Box sx={{ p: 2 }}>
        &#x3C;Paper sx={{ p: 3 }}>
            {/* Content */}
        &#x3C;/Paper>
    &#x3C;/Box>
);

};

export default MyComponent;

For complete examples, see resources/complete-examples.md

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

frontend-dev-guidelines

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

github-pr-review

mobile-development

code-review