Frontend Development Guidelines

What Is This

The Frontend Development Guidelines skill provides a comprehensive set of conventions and technical patterns for building modern frontend applications using React and TypeScript. It targets developers working with key tools such as Suspense, React.lazy, TanStack Query, TanStack Router, and Material UI (MUI) v7. The guidelines cover component creation, code structure, lazy loading, data fetching, performance optimization, styling, and TypeScript best practices to ensure scalable, maintainable, and high-performing frontend codebases.

These guidelines are particularly focused on establishing a robust development workflow for feature-rich, production-grade React applications. The main objectives are to standardize frontend code, improve developer efficiency, and maximize application performance by leveraging contemporary React patterns and supporting libraries.

Why Use It

Adhering to these guidelines offers several benefits:

• Consistency: Ensures that all contributors follow the same patterns, making code easier to understand, maintain, and scale.
• Performance: Emphasizes lazy loading, Suspense, and optimized data fetching for faster load times and better runtime efficiency.
• Scalability: Encourages proper file structure and modularity, which supports the seamless addition of new features and components.
• Type Safety: Leverages TypeScript best practices to catch errors at compile time and enhance maintainability.
• Modern Practices: Utilizes the latest advancements in React, such as Suspense for data fetching and component loading, and up-to-date libraries like TanStack Query and Router.

How to Use It

Apply the following checklist and patterns when developing frontend features, components, or pages in React/TypeScript projects:

1. Component

Creation

• Use the React.FC<Props> pattern to define components with explicit prop types.

• For large or rarely used components, implement lazy loading with React.lazy:

  typescript

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

• Always wrap lazy-loaded components in a suspense loader for proper loading feedback:

  tsx

  <SuspenseLoader>
    <HeavyComponent />
  </SuspenseLoader>

  The SuspenseLoader component should provide a user-friendly loading indicator.

2. Data

Fetching

• Use useSuspenseQuery from TanStack Query for data fetching, which integrates smoothly with React Suspense:

  typescript

  const { data } = useSuspenseQuery(['users', userId], fetchUser);

• Do not use early returns with loading spinners; rely on Suspense boundaries instead.

3. File

Organization

• Structure your codebase using a features directory. Group related components, hooks, and state logic together for improved modularity.

  plaintext

  src/
    features/
      user/
        UserProfile.tsx
        useUserData.ts

• Use import aliases for cleaner and more readable imports:

  typescript

  import { UserProfile } from '~features/user/UserProfile';
  import { Button } from '~components/Button';

4. Styling

• Use MUI v7 for styling components. If a component has fewer than 100 lines of styles, use inline styling. For larger style blocks, extract them to a separate file.

  tsx

  // Inline styles example (for small components):
  <Box sx={{ padding: 2, backgroundColor: 'primary.main' }}>...</Box>

  typescript

  // For >100 lines of styles, create UserProfile.styles.ts and import them.

5. Performance

Optimization

• Lazy load heavy components and wrap with Suspense to minimize initial bundle size.

• Use useCallback for event handlers passed to child components to prevent unnecessary re-renders:

  typescript

  const handleClick = useCallback(() => {
    // logic
  }, []);

6. TypeScript Best

Practices

• Define explicit prop types and interfaces.

• Place default exports at the bottom of each file for consistency.

  typescript

  export default UserProfile;

When to Use It

Utilize these guidelines in the following scenarios:

• Creating new React components or pages
• Adding or refactoring features within a frontend application
• Implementing data fetching logic with TanStack Query
• Setting up or modifying routes with TanStack Router
• Styling components using MUI v7
• Optimizing performance for large or complex components
• Organizing code in medium to large scale frontend projects
• Applying TypeScript for robust type safety

Important Notes

• Always wrap lazy-loaded components with Suspense to avoid rendering issues or blank screens during loading states.
• Never use early returns for loading states inside components; rely on Suspense boundaries and fallback UIs.
• Use import path aliases (~/, ~types, ~components, ~features) for improved readability and maintainability.
• Inline styles should be limited to components with fewer than 100 lines of style code to avoid cluttering component logic.
• Group all feature-related logic and components within the features directory to maintain a scalable project structure.
• Event handlers passed to children must be memoized with useCallback to prevent unnecessary re-renders and maintain optimal performance.
• Always export your component as the default export at the end of the file for consistency across the codebase.

By following these guidelines, teams can ensure a clean, maintainable, and high-performance frontend codebase that leverages modern React and TypeScript patterns.