fullstack-guide

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)
• Event handlers with useCallback
• No early returns for loading states

---

Core Patterns

Component Pattern

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;

Data Fetching

// Use useSuspenseQuery - No isLoading checks needed!
const { data } = useSuspenseQuery({
    queryKey: ['myEntity', id],
    queryFn: () => myFeatureApi.getEntity(id),
});

// data is ALWAYS defined (Suspense handles loading)